oas 14.8.1 → 16.0.2

package/@types/index.d.ts

@@ -0,0 +1,141 @@
+export = Oas;
+declare class Oas {
+    constructor(oas: any, user: any);
+    user: any;
+    _promises: any[];
+    _dereferencing: {
+        processing: boolean;
+        complete: boolean;
+    };
+    getVersion(): any;
+    url(selected: number, variables: any): any;
+    variables(selected?: number): any;
+    defaultVariables(selected?: number): {};
+    splitUrl(selected?: number): any;
+    /**
+     * 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 {String} baseUrl
+     * @returns {Object|Boolean}
+     */
+    splitVariables(baseUrl: string): Object | boolean;
+    /**
+     * Replace templated variables with supplied data in a given URL.
+     *
+     * There are a couple ways that this will utilize variable data:
+     *
+     *  - If data is stored in `this.user` and it matches up with the variable name in the URL user data
+     *    will always take priority. See `getUserVariable` for some more information on how this data is pulled from
+     *    `this.user`.
+     *  - Supplying a `variables` object. This incoming `variables` object can be two formats:
+     *    `{ variableName: { default: 'value' } }` and `{ variableName: 'value' }`. If the former is present, that will
+     *    take prescendence over the latter.
+     *
+     * If no variables supplied match up with the template name, the template name will instead be used as the variable
+     * data.
+     *
+     * @param {String} url
+     * @param {Object} variables
+     * @returns String
+     */
+    replaceUrl(url: string, variables?: Object): any;
+    operation(path: any, method: any, opts?: {}): Operation.Webhook | Operation;
+    findOperationMatches(url: any): {
+        url: {
+            origin: any;
+            path: any;
+            nonNormalizedPath: string;
+            slugs: {};
+        };
+        operation: any;
+        match: import("path-to-regexp").Match<object>;
+    }[];
+    /**
+     * 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 {String} url
+     * @param {String} method
+     * @return {(Object|undefined)}
+     */
+    findOperation(url: string, method: string): (Object | undefined);
+    /**
+     * 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 {String} url
+     * @return {(Object|undefined)}
+     */
+    findOperationWithoutMethod(url: string): (Object | undefined);
+    /**
+     * 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 {String} url
+     * @param {String} method
+     * @return {(Operation|undefined)}
+     */
+    getOperation(url: string, method: string): (Operation | undefined);
+    /**
+     * With an object of user information, retrieve an appropriate API key from the current OAS definition.
+     *
+     * @see {@link https://docs.readme.com/docs/passing-data-to-jwt}
+     * @param {Object} user
+     * @param {Boolean|String} selectedApp
+     */
+    getAuth(user: Object, selectedApp?: boolean | string): Record<string, unknown>;
+    /**
+     * 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#oasObject}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#openapi-object}
+     * @returns {object}
+     */
+    getPaths(): object;
+    /**
+     * Returns the `webhooks` 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#oasObject}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#openapi-object}
+     * @returns {object}
+     */
+    getWebhooks(): object;
+    /**
+     * Return an array of all tag names that exist on this API definition.
+     *
+     * Note: This method right now does **not** factor in webhooks that have tags.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#oasObject}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#openapi-object}
+     * @param {boolean} setIfMissing If a tag is not present on an operation that operations path will be added into the
+     *    list of tags returned.
+     * @returns {array}
+     */
+    getTags(setIfMissing?: boolean): any;
+    /**
+     * Dereference the current OAS definition so it can be parsed free of worries of `$ref` schemas and circular
+     * structures.
+     *
+     * @returns {Promise<void>}
+     */
+    dereference(): Promise<void>;
+}
+declare namespace Oas {
+    export { Operation, Callback, Webhook, utils };
+}
+import Operation = require("./operation");
+import { Callback } from "./operation";
+import { Webhook } from "./operation";
+import utils_1 = require("./utils");
+import utils = utils_1.default;

package/@types/lib/find-schema-definition.d.ts

@@ -0,0 +1 @@
+export default function findSchemaDefinition($ref: string, definitions?: {}): false | any;

package/@types/lib/get-auth.d.ts

@@ -0,0 +1,19 @@
+import { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
+declare type primitiveType = string | number;
+declare type selectedAppType = primitiveType;
+declare type authKey = null | unknown | {
+    user: primitiveType;
+    password: primitiveType;
+};
+interface User {
+    [key: string]: unknown;
+    keys?: Array<{
+        name: string;
+        user?: primitiveType;
+        pass?: primitiveType;
+        [key: string]: unknown;
+    }>;
+}
+declare function getByScheme(user: User, scheme?: any, selectedApp?: selectedAppType): authKey;
+export { getByScheme };
+export default function getAuth(oas: OpenAPIV3.Document | OpenAPIV3_1.Document, user: User, selectedApp?: selectedAppType): Record<string, unknown>;

package/@types/lib/get-mediatype-examples.d.ts

@@ -0,0 +1,2 @@
+declare function _exports(mediaType: string, mediaTypeObject: object, opts?: object): any;
+export = _exports;

package/@types/lib/get-schema.d.ts

@@ -0,0 +1,2 @@
+declare function _exports(pathOperation: any, oas: any): any;
+export = _exports;

package/@types/lib/get-user-variable.d.ts

@@ -0,0 +1,2 @@
+declare function _exports(user: any, property: any, selectedApp?: boolean): any;
+export = _exports;

package/@types/lib/matches-mimetype.d.ts

@@ -0,0 +1,5 @@
+export function formUrlEncoded(contentType: any): any;
+export function json(contentType: any): any;
+export function multipart(contentType: any): any;
+export function wildcard(contentType: any): boolean;
+export function xml(contentType: any): any;

package/@types/lib/openapi-to-json-schema.d.ts

@@ -0,0 +1,51 @@
+export = toJSONSchema;
+/**
+ * Given an OpenAPI-flavored JSON Schema, make an effort to modify it so it's shaped more towards stock JSON Schema.
+ *
+ * Why do this?
+ *
+ *  1. OpenAPI 3.0.x supports its own flavor of JSON Schema that isn't fully compatible with most JSON Schema tooling
+ *    (like `@readme/oas-form` or `@rjsf/core`).
+ *  2. While validating an OpenAPI definition will prevent corrupted or improper schemas from occuring, we have a lot of
+ *    legacy schemas in ReadMe that were ingested before we had proper validation in place, and as a result have some
+ *    API definitions that will not pass validation right now. In addition to reshaping OAS-JSON Schema into JSON Schema
+ *    this library will also fix these improper schemas: things like `type: object` having `items` instead of
+ *    `properties`, `type: array` missing `items`, or `type` missing completely on a schema.
+ *  3. Additionally due to OpenAPI 3.0.x not supporting JSON Schema, in order to support the `example` keyword that OAS
+ *    supports, we need to do some work in here to remap it into `examples`. However, since all we care about in respect
+ *    to examples for usage within `@readme/oas-form`, we're only retaining primitives. This *slightly* deviates from
+ *    JSON Schema in that JSON Schema allows for any schema to be an example, but since `@readme/oas-form` can only
+ *    actually **render** primitives, that's what we're retaining.
+ *  4. Though OpenAPI 3.1 does support full JSON Schema, this library should be able to handle it without any problems.
+ *
+ * And why use this over `@openapi-contrib/openapi-schema-to-json-schema`? Fortunately and unfortunately we've got a lot
+ * of API definitions in our database that aren't currently valid so we need to have a lot of bespoke handling for odd
+ * quirks, typos, and missing declarations that they've got.
+ *
+ * @see {@link https://json-schema.org/draft/2019-09/json-schema-validation.html{}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md}
+ * @param {Object} data
+ * @param {Object} opts
+ * @param {String} opts.currentLocation - Current location within the schema -- this is a JSON pointer.
+ * @param {Object} opts.globalDefaults - Object containing a global set of defaults that we should apply to schemas that match it.
+ * @param {Boolean} opts.isPolymorphicAllOfChild - Is this schema the child of a polymorphic `allOf` schema?
+ * @param {Object[]} opts.prevSchemas - Array of parent schemas to utilize when attempting to path together examples.
+ * @param {Function} opts.refLogger - A function that's called anytime a (circular) `$ref` is found.
+ */
+declare function toJSONSchema(data: Object, opts?: {
+    currentLocation: string;
+    globalDefaults: Object;
+    isPolymorphicAllOfChild: boolean;
+    prevSchemas: Object[];
+    refLogger: Function;
+}): {
+    constructor: Function;
+    toString(): string;
+    toLocaleString(): string;
+    valueOf(): Object;
+    hasOwnProperty(v: PropertyKey): boolean;
+    isPrototypeOf(v: Object): boolean;
+    propertyIsEnumerable(v: PropertyKey): boolean;
+} | {
+    $ref: any;
+};

package/@types/operation/get-callback-examples.d.ts

@@ -0,0 +1,2 @@
+declare function _exports(operation: object): any[];
+export = _exports;

package/@types/operation/get-parameters-as-json-schema.d.ts

@@ -0,0 +1,13 @@
+declare function _exports(path: string, operation: any, oas: any, globalDefaults?: Object): any;
+declare namespace _exports {
+    export { types };
+}
+export = _exports;
+declare namespace types {
+    const path: string;
+    const query: string;
+    const body: string;
+    const cookie: string;
+    const formData: string;
+    const header: string;
+}

package/@types/operation/get-requestbody-examples.d.ts

@@ -0,0 +1,5 @@
+declare function _exports(operation: object): (false | {
+    mediaType: string;
+    examples: any;
+})[];
+export = _exports;

package/@types/operation/get-response-as-json-schema.d.ts

@@ -0,0 +1,6 @@
+declare function _exports(operation: any, oas: any, statusCode: string): {
+    type: any;
+    schema: any;
+    label: string;
+}[];
+export = _exports;

package/@types/operation/get-response-examples.d.ts

@@ -0,0 +1,5 @@
+declare function _exports(operation: object): (false | {
+    status: string;
+    mediaTypes: {};
+})[];
+export = _exports;

package/@types/operation.d.ts

@@ -0,0 +1,175 @@
+export = Operation;
+declare class Operation {
+    constructor(oas: any, path: any, method: any, operation: any);
+    schema: any;
+    oas: any;
+    path: any;
+    method: any;
+    contentType: any;
+    requestBodyExamples: (false | {
+        mediaType: string;
+        examples: any;
+    })[];
+    responseExamples: (false | {
+        status: string;
+        mediaTypes: {};
+    })[];
+    callbackExamples: any[];
+    getContentType(): any;
+    isFormUrlEncoded(): any;
+    isMultipart(): any;
+    isJson(): any;
+    isXml(): any;
+    /**
+     * Returns an array of all security requirements associated wtih this operation. If none are defined at the operation
+     * level, the securities for the entire API definition are returned (with an empty array as a final fallback).
+     *
+     * @returns {array}
+     */
+    getSecurity(): any;
+    /**
+     * @see {@link https://swagger.io/docs/specification/authentication/#multiple}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-requirement-object}
+     * @param {boolean} filterInvalid Optional flag that, when set to `true`, filters out invalid/nonexistent security
+     *    schemes, rather than returning `false`.
+     * @returns {array} An array of arrays of objects of grouped security schemes. The inner array determines and-grouped
+     *    security schemes, the outer array determines or-groups.
+     */
+    getSecurityWithTypes(filterInvalid?: boolean): any;
+    /**
+     * @returns An object where the keys are unique scheme types,
+     * and the values are arrays containing each security scheme of that type.
+     */
+    prepareSecurity(): any;
+    getHeaders(): {
+        request: any[];
+        response: any[];
+    };
+    headers: {
+        request: any[];
+        response: any[];
+    };
+    /**
+     * Determine if the operation has an operation present in its schema.
+     *
+     * @return {boolean}
+     */
+    hasOperationId(): boolean;
+    /**
+     * Get an `operationId` for this operation. If one is not present (it's not required by the spec!) a hash of the path
+     * and method will be returned instead.
+     *
+     * @return {string}
+     */
+    getOperationId(): string;
+    /**
+     * Return an array of all tags, and their metadata, that exist on this operation.
+     *
+     * @returns {array}
+     */
+    getTags(): any;
+    /**
+     * Return is the operation is flagged as `deprecated` or not.
+     *
+     * @returns {boolean}
+     */
+    isDeprecated(): boolean;
+    /**
+     * Return the parameters (non-request body) on the operation.
+     *
+     * @todo This should also pull in common params.
+     * @return {array}
+     */
+    getParameters(): any;
+    /**
+     * Convert the operation into an array of JSON Schema for each available type of parameter available on the operation.
+     * `globalDefaults` contains an object of user defined parameter defaults used in constructSchema
+     *
+     * @param {Object} globalDefaults
+     * @return {array}
+     */
+    getParametersAsJsonSchema(globalDefaults: Object): any;
+    /**
+     * Get a single response for this status code, formatted as JSON schema
+     * @param {*} statusCode
+     * @returns
+     */
+    getResponseAsJsonSchema(statusCode: any): {
+        type: any;
+        schema: any;
+        label: string;
+    }[];
+    /**
+     * Get an array of all valid response status codes for this operation
+     * @param {*} statusCode
+     * @returns
+     */
+    getResponseStatusCodes(): string[];
+    /**
+     * Determine if the operation has a request body.
+     *
+     * @return {boolean}
+     */
+    hasRequestBody(): boolean;
+    /**
+     * Retrieve an array of request body examples that this operation has.
+     *
+     * @returns {array}
+     */
+    getRequestBodyExamples(): any;
+    /**
+     * Return a specific response out of the operation by a given HTTP status code.
+     *
+     * @param {integer} statusCode
+     * @return {(boolean|object)}
+     */
+    getResponseByStatusCode(statusCode: any): (boolean | object);
+    /**
+     * Retrieve an array of response examples that this operation has.
+     *
+     * @returns {array}
+     */
+    getResponseExamples(): any;
+    /**
+     * Determine if the operation has callbacks.
+     *
+     * @return {boolean}
+     */
+    hasCallbacks(): boolean;
+    /**
+     * Retrieve a specific callback
+     *
+     * @returns {Operation}
+     */
+    getCallback(identifier: any, expression: any, method: any): Operation;
+    /**
+     * Retrieve an array of operations created from each callback.
+     *
+     * @returns {array}
+     */
+    getCallbacks(): any;
+    /**
+     * Retrieve an array of callback examples that this operation has.
+     *
+     * @returns {array}
+     */
+    getCallbackExamples(): any;
+}
+declare namespace Operation {
+    export { Callback, Webhook };
+}
+declare class Callback extends Operation {
+    constructor(oas: any, path: any, method: any, operation: any, identifier: any);
+    identifier: any;
+    /**
+     * Return the primary identifier for this callback.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#callback-object}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject}
+     *
+     * @returns {string}
+     */
+    getIdentifier(): string;
+}
+declare class Webhook extends Operation {
+}

package/@types/samples/index.d.ts

@@ -0,0 +1 @@
+export var sampleFromSchema: any;

package/@types/samples/utils.d.ts

@@ -0,0 +1,5 @@
+export function usesPolymorphism(schema: any): string;
+export function objectify(thing: any): any;
+export function normalizeArray(arr: any): any[];
+export function isFunc(thing: any): boolean;
+export function deeplyStripKey(input: any, keyToStrip: any, predicate?: () => boolean): any;

package/@types/utils.d.ts

@@ -0,0 +1,21 @@
+import findSchemaDefinition from './lib/find-schema-definition';
+declare const _default: {
+    findSchemaDefinition: typeof findSchemaDefinition;
+    getSchema: (pathOperation: any, oas: any) => any;
+    jsonSchemaTypes: {
+        path: string;
+        query: string;
+        body: string;
+        cookie: string;
+        formData: string;
+        header: string;
+    };
+    matchesMimeType: {
+        formUrlEncoded: (contentType: any) => any;
+        json: (contentType: any) => any;
+        multipart: (contentType: any) => any;
+        wildcard: (contentType: any) => boolean;
+        xml: (contentType: any) => any;
+    };
+};
+export default _default;

package/CHANGELOG.md

@@ -1,3 +1,58 @@
+## <small>16.0.2 (2021-10-28)</small>
+
+* fix: minor typescript cleanup ([f032a30](https://github.com/readmeio/oas/commit/f032a30))
+
+
+
+## <small>16.0.1 (2021-10-28)</small>
+
+* feat: exporting the internal `utils` library to the main export ([2eaeac7](https://github.com/readmeio/oas/commit/2eaeac7))
+* chore: removing an unneeded eslint exclusion ([99151d3](https://github.com/readmeio/oas/commit/99151d3))
+
+
+
+## 16.0.0 (2021-10-28)
+
+> **BREAKING CHANGE**
+>
+> This library no longer ships with a browser-targeted dist. If you need to the tooling side of this library within a browser you'll need to handle bundling with your favorite tool for doing so.
+
+* fix: removing webpack and a browser-targeted export (#529) ([a4e84c8](https://github.com/readmeio/oas/commit/a4e84c8)), closes [#529](https://github.com/readmeio/oas/issues/529)
+
+
+
+## 15.0.0 (2021-10-28)
+
+> **BREAKING CHANGE**
+>
+> Lots of changes here!
+>
+> - We're starting a slow process to transition the library to Typescript so a couple sub-libraries here now have exposed Typescript declaration files.
+> - The `flattenArray` and `flattenSchema` exports have been removed.
+> - The primary entrypoint for the library has been moved from `src/` to `dist/` so if we don't export something you're using you'll likely have a tough time to access it. If you need something let us know and we'll add an export for it (we're also open to PR's!).
+>
+> We're also starting to adopt OpenAPI 3.1 and have access a heap of new accessors in the `Oas` and `Operation` classes as well as extending support for it immediately to the `oas validate` CLI command. 🥳
+
+* feat: add callback accessors into operation class (#515) ([c1759bd](https://github.com/readmeio/oas/commit/c1759bd)), closes [#515](https://github.com/readmeio/oas/issues/515)
+* feat: adding a `getIdentifier` accessor on the Callback class (#528) ([fb65142](https://github.com/readmeio/oas/commit/fb65142)), closes [#528](https://github.com/readmeio/oas/issues/528)
+* feat: adding accessors for spec versions, paths, webhooks, and tags (#516) ([2daaf67](https://github.com/readmeio/oas/commit/2daaf67)), closes [#516](https://github.com/readmeio/oas/issues/516)
+* feat: supporting OpenAPI 3.1 within the CLI tooling (#514) ([d1463b3](https://github.com/readmeio/oas/commit/d1463b3)), closes [#514](https://github.com/readmeio/oas/issues/514)
+* feat: webpack 5 + typescript beginnings (#518) ([a59fd9b](https://github.com/readmeio/oas/commit/a59fd9b)), closes [#518](https://github.com/readmeio/oas/issues/518)
+* chore(deps-dev): bump @babel/core from 7.15.5 to 7.15.8 (#527) ([b90d64e](https://github.com/readmeio/oas/commit/b90d64e)), closes [#527](https://github.com/readmeio/oas/issues/527)
+* chore(deps-dev): bump @babel/preset-env from 7.15.6 to 7.15.8 (#526) ([e32b2ad](https://github.com/readmeio/oas/commit/e32b2ad)), closes [#526](https://github.com/readmeio/oas/issues/526)
+* chore(deps-dev): bump @commitlint/cli from 13.2.0 to 13.2.1 (#522) ([b42ee68](https://github.com/readmeio/oas/commit/b42ee68)), closes [#522](https://github.com/readmeio/oas/issues/522)
+* chore(deps-dev): bump babel-loader from 8.2.2 to 8.2.3 (#524) ([f57fea4](https://github.com/readmeio/oas/commit/f57fea4)), closes [#524](https://github.com/readmeio/oas/issues/524)
+* chore(deps-dev): bump husky from 7.0.2 to 7.0.4 (#521) ([6ca7d93](https://github.com/readmeio/oas/commit/6ca7d93)), closes [#521](https://github.com/readmeio/oas/issues/521)
+* chore(deps-dev): bump jest from 27.2.4 to 27.3.1 (#520) ([4c53b4b](https://github.com/readmeio/oas/commit/4c53b4b)), closes [#520](https://github.com/readmeio/oas/issues/520)
+* chore(deps): bump actions/checkout from 2.3.4 to 2.3.5 (#519) ([bdd7c3c](https://github.com/readmeio/oas/commit/bdd7c3c)), closes [#519](https://github.com/readmeio/oas/issues/519)
+* chore(deps): bump inquirer from 8.1.5 to 8.2.0 (#523) ([d675cbe](https://github.com/readmeio/oas/commit/d675cbe)), closes [#523](https://github.com/readmeio/oas/issues/523)
+* chore(deps): bump swagger-inline from 4.2.1 to 4.2.2 (#525) ([60a9fa2](https://github.com/readmeio/oas/commit/60a9fa2)), closes [#525](https://github.com/readmeio/oas/issues/525)
+* fix: adding a base undefined callbackExamples property to the Oas class ([0d5a233](https://github.com/readmeio/oas/commit/0d5a233))
+* fix: deprecatedProps inherits parent schemas type (#517) ([b7277d3](https://github.com/readmeio/oas/commit/b7277d3)), closes [#517](https://github.com/readmeio/oas/issues/517)
+* build: release 14.8.1 ([c9ce444](https://github.com/readmeio/oas/commit/c9ce444))
+
+
+
 ## 14.8.0 (2021-10-18)
 
 * feat: separate deprecated params for display (#513) ([9817b3e](https://github.com/readmeio/oas/commit/9817b3e)), closes [#513](https://github.com/readmeio/oas/issues/513)

package/README.md

@@ -57,4 +57,4 @@ require('oas')
 
 Also exposed within the main `oas` export is an `Operation` class that can help you manage and retrieve specific data from an API operation.
 
-> To use a compiled version of this offering within a browser, you can load `oas/dist`
+> If you need to use this library within a browser you'll likely need to use a bundler like [Webpack](https://webpack.js.org/) or [Rollup](https://rollupjs.org/).