oas 16.0.2 → 17.1.0

package/@types/index.d.ts

@@ -1,17 +1,93 @@
-export = Oas;
-declare class Oas {
-    constructor(oas: any, user: any);
-    user: any;
-    _promises: any[];
-    _dereferencing: {
+import type * as RMOAS from './rmoas.types';
+import type { MatchResult } from 'path-to-regexp';
+import Operation, { Callback, Webhook } from './operation';
+import utils from './utils';
+declare type PathMatch = {
+    url: {
+        origin: string;
+        path: string;
+        nonNormalizedPath: string;
+        slugs: Record<string, string>;
+        method?: RMOAS.HttpMethods;
+    };
+    operation: RMOAS.PathsObject;
+    match?: MatchResult;
+};
+declare type PathMatches = Array<PathMatch>;
+declare type Variables = Record<string, string | number | Array<{
+    default?: string | number;
+}> | {
+    default?: string | number;
+}>;
+export default class Oas {
+    /**
+     * An OpenAPI API Definition.
+     */
+    api: RMOAS.OASDocument;
+    /**
+     * The current user that we should use when pulling auth tokens from security schemes.
+     */
+    user: RMOAS.User;
+    /**
+     * Internal storage array that the library utilizes to keep track of the times the {@see Oas.dereference} has been
+     * called so that if you initiate multiple promises they'll all end up returning the same data set once the initial
+     * dereference call completed.
+     *
+     * @todo These are always `Promise.resolve` and `Promise.reject`. Make these types more specific than `any`.
+     */
+    protected promises: Array<{
+        resolve: any;
+        reject: any;
+    }>;
+    /**
+     * Internal storage array that the library utilizes to keep track of its `dereferencing` state so it doesn't initiate
+     * multiple dereferencing processes.
+     */
+    protected dereferencing: {
         processing: boolean;
         complete: boolean;
     };
-    getVersion(): any;
-    url(selected: number, variables: any): any;
-    variables(selected?: number): any;
-    defaultVariables(selected?: number): {};
-    splitUrl(selected?: number): any;
+    /**
+     * @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: RMOAS.OASDocument, user?: RMOAS.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.
+     * @returns An instance of the Oas class.
+     */
+    static init(oas: Record<string, unknown> | RMOAS.OASDocument, user?: RMOAS.User): Oas;
+    /**
+     * @returns The OpenAPI version that this API definition is targeted for.
+     */
+    getVersion(): string;
+    /**
+     * @returns The current OpenAPI API Definition.
+     */
+    getDefinition(): RMOAS.OASDocument;
+    url(selected?: number, variables?: Variables): string;
+    variables(selected?: number): {
+        [variable: string]: import("openapi-types").OpenAPIV3.ServerVariableObject;
+    };
+    defaultVariables(selected?: number): Record<string, unknown>;
+    splitUrl(selected?: number): ({
+        type: string;
+        value: string;
+        key: string;
+        description?: undefined;
+        enum?: undefined;
+    } | {
+        type: string;
+        value: string;
+        key: string;
+        description: string;
+        enum: string[] | [string, ...string[]];
+    })[];
     /**
      * 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.
@@ -23,10 +99,13 @@ declare class Oas {
      *
      * Re-supplying this data to `oas.url()` should return the same URL you passed into this method.
      *
-     * @param {String} baseUrl
-     * @returns {Object|Boolean}
+     * @param baseUrl A given URL to extract server variables out of.
+     * @returns The extracted server variables and the configured server that they were matched to.
      */
-    splitVariables(baseUrl: string): Object | boolean;
+    splitVariables(baseUrl: string): false | {
+        selected: number;
+        variables: Record<string, string | number>;
+    };
     /**
      * Replace templated variables with supplied data in a given URL.
      *
@@ -42,75 +121,80 @@ declare class Oas {
      * 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>;
-    }[];
+     * @param url A URL to swap variables into.
+     * @param variables An object containing variables to swap into the URL.
+     * @returns The new URL with the variables.
+     */
+    replaceUrl(url: string, variables?: Variables): string;
+    /**
+     * 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.
+     * @param opts Options
+     * @param opts.isWebhook If you prefer to first look for a webhook with this path and method.
+     * @returns The found Operation or Webhook.
+     */
+    operation(path: string, method: RMOAS.HttpMethods, opts?: {
+        isWebhook?: boolean;
+    }): Operation;
+    findOperationMatches(url: string): PathMatches;
     /**
      * 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)}
+     * @param url A full URL to look up.
+     * @param method The cooresponding HTTP method to look up.
+     * @returns An object containing matches that were discovered in the API definition.
      */
-    findOperation(url: string, method: string): (Object | undefined);
+    findOperation(url: string, method: RMOAS.HttpMethods): PathMatch;
     /**
      * 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)}
+     * @param url A full URL to look up.
+     * @returns An object containing matches that were discovered in the API definition.
      */
-    findOperationWithoutMethod(url: string): (Object | undefined);
+    findOperationWithoutMethod(url: string): PathMatch;
     /**
      * 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)}
+     * @param url A full URL to look up.
+     * @param method The cooresponding HTTP method to look up.
+     * @returns The found operation or webhook.
      */
-    getOperation(url: string, method: string): (Operation | undefined);
+    getOperation(url: string, method: RMOAS.HttpMethods): Operation;
     /**
      * 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
+     * @param user User
+     * @param selectedApp The user app to retrieve an auth key for.
+     * @returns Found auth keys for the found security schemes.
      */
-    getAuth(user: Object, selectedApp?: boolean | string): Record<string, unknown>;
+    getAuth(user: RMOAS.User, selectedApp?: string | number): {
+        [x: 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}
+     * @returns The Paths that exist on this API definition.
      */
-    getPaths(): object;
+    getPaths(): Record<string, Record<RMOAS.HttpMethods, Operation | Webhook>>;
     /**
      * 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}
+     * @returns The Webhooks that exist on this API definition.
      */
-    getWebhooks(): object;
+    getWebhooks(): Record<string, Record<RMOAS.HttpMethods, Webhook>>;
     /**
      * Return an array of all tag names that exist on this API definition.
      *
@@ -120,22 +204,33 @@ declare class Oas {
      * @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}
+     * @returns An array of tags.
+     */
+    getTags(setIfMissing?: boolean): unknown[];
+    /**
+     * 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#specificationExtensions}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions}
+     * @param extension Specification extension to lookup.
+     * @returns The extension exists.
      */
-    getTags(setIfMissing?: boolean): any;
+    hasExtension(extension: string): boolean;
+    /**
+     * 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#specificationExtensions}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions}
+     * @param extension Specification extension to lookup.
+     * @returns The extension contents if it was found.
+     */
+    getExtension(extension: string): unknown;
     /**
      * Dereference the current OAS definition so it can be parsed free of worries of `$ref` schemas and circular
      * structures.
      *
-     * @returns {Promise<void>}
+     * @returns A post-dereference Promise.
      */
-    dereference(): Promise<void>;
-}
-declare namespace Oas {
-    export { Operation, Callback, Webhook, utils };
+    dereference(): Promise<unknown>;
 }
-import Operation = require("./operation");
-import { Callback } from "./operation";
-import { Webhook } from "./operation";
-import utils_1 = require("./utils");
-import utils = utils_1.default;
+export { Operation, Callback, Webhook, utils };

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

@@ -1 +1,6 @@
-export default function findSchemaDefinition($ref: string, definitions?: {}): false | any;
+/**
+ * @param $ref Reference to look up a schema for.
+ * @param definitions OpenAPI definition to look for the `$ref` pointer in.
+ * @returns Found schema.
+ */
+export default function findSchemaDefinition($ref: string, definitions?: {}): any;

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

@@ -1,19 +1,32 @@
-import { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
-declare type primitiveType = string | number;
-declare type selectedAppType = primitiveType;
+import type * as RMOAS from '../rmoas.types';
+import type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 declare type authKey = null | unknown | {
-    user: primitiveType;
-    password: primitiveType;
+    user: string | number;
+    password: string | number;
 };
-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>;
+/**
+ * Retrieve auth keys for a specific security scheme for a given user for a specific "app" that they have configured.
+ *
+ * For `scheme` we're typing it to a union of `SecurityScheme` and `any` because we have handling and tests for an
+ * unknown or unrecognized `type` and though it's not possible with the `SecurityScheme.type` to be unrecognized it may
+ * still be possible to get an unrecognized scheme with this method in the wild as we have API definitions in our
+ * database that were ingested before we had good validation in place.
+ *
+ * @param user User
+ * @param scheme Security scheme to get auth keys for.
+ * @param selectedApp The user app to retrieve an auth key for.
+ * @returns The found auth key for this security scheme.
+ */
+export declare function getByScheme(user: RMOAS.User, scheme?: RMOAS.KeyedSecuritySchemeObject, selectedApp?: string | number): authKey;
+/**
+ * Retrieve auth keys for an API definition from a given user for a specific "app" that they have configured.
+ *
+ * @param api API definition
+ * @param user User
+ * @param selectedApp The user app to retrieve an auth key for.
+ * @returns Found auth keys for the found security schemes.
+ */
+export default function getAuth(api: OpenAPIV3.Document | OpenAPIV3_1.Document, user: RMOAS.User, selectedApp?: string | number): {
+    [x: string]: unknown;
+};
+export {};

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

@@ -1,2 +1,22 @@
-declare function _exports(mediaType: string, mediaTypeObject: object, opts?: object): any;
-export = _exports;
+import type * as RMOAS from '../rmoas.types';
+export declare type MediaTypeExample = {
+    summary?: string;
+    title?: string;
+    description?: string;
+    value: unknown;
+};
+/**
+ * Extracts an array of examples from an OpenAPI Media Type Object. The example will either come from the `example`
+ * property, the first item in an `examples` array, or if none of those are present it will generate an example based
+ * off its schema.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#mediaTypeObject}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#mediaTypeObject}
+ * @param mediaType The media type that we're looking for examples for.
+ * @param mediaTypeObject The media type object that we're looking for examples for.
+ * @param opts Options
+ * @param opts.includeReadOnly If you wish to include data that's flagged as `readOnly`.
+ * @param opts.includeWriteOnly If you wish to include data that's flatted as `writeOnly`.
+ * @returns Array of media type examples.
+ */
+export default function getMediaTypeExamples(mediaType: string, mediaTypeObject: RMOAS.MediaTypeObject, opts?: {}): MediaTypeExample[];

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

@@ -1,2 +1,21 @@
-declare function _exports(pathOperation: any, oas: any): any;
-export = _exports;
+import type * as RMOAS from '../rmoas.types';
+/**
+ * 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.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#fixed-fields-8}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#fixed-fields-8}
+ * @param operation Operation to look for a primary requestBody schema in.
+ * @param api The API definition that this operation exists within.
+ * @returns The found requestBody schema.
+ */
+export default function getSchema(operation: RMOAS.OperationObject, api?: RMOAS.OASDocument | {
+    [schemaType: string]: {
+        [key: string]: RMOAS.SchemaObject;
+    };
+}): {
+    type: string;
+    schema: any;
+};

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

@@ -1,2 +1,11 @@
-declare function _exports(user: any, property: any, selectedApp?: boolean): any;
-export = _exports;
+import type * as RMOAS from '../rmoas.types';
+/**
+ * Retrieve a user variable off of a given user.
+ *
+ * @see {@link https://docs.readme.com/docs/passing-data-to-jwt}
+ * @param user The user to get a user variable for.
+ * @param property The name of the variable to retrieve.
+ * @param selectedApp The user app to retrieve an auth key for.
+ * @returns Found user variable.
+ */
+export default function getUserVariable(user: RMOAS.User, property: string, selectedApp?: string | number): unknown;

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

@@ -1,5 +1,8 @@
-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;
+declare const _default: {
+    formUrlEncoded: (mimeType: string) => boolean;
+    json: (contentType: string) => boolean;
+    multipart: (contentType: string) => boolean;
+    wildcard: (contentType: string) => boolean;
+    xml: (contentType: string) => boolean;
+};
+export default _default;

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

@@ -1,2 +1,19 @@
-declare function _exports(operation: object): any[];
-export = _exports;
+import type * as RMOAS from '../rmoas.types';
+export declare type CallbackExamples = {
+    identifier: string;
+    expression: string;
+    method: string;
+    example: unknown;
+}[];
+/**
+ * With an OpenAPI Operation Object return back an array of examples for any callbacks that may be present.
+ *
+ * @param operation Operation to retrieve callback examples from.
+ * @returns An an array of callback examples.
+ */
+export default function getCallbackExamples(operation: RMOAS.OperationObject): {
+    identifier: string;
+    expression: string;
+    method: string;
+    example: unknown;
+}[];

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

@@ -1,4 +1,4 @@
-declare function _exports(path: string, operation: any, oas: any, globalDefaults?: Object): any;
+declare function _exports(path: string, operation: any, api: any, globalDefaults?: Object): any;
 declare namespace _exports {
     export { types };
 }

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

@@ -1,5 +1,10 @@
-declare function _exports(operation: object): (false | {
+import type * as RMOAS from '../rmoas.types';
+export declare type RequestBodyExamples = {
     mediaType: string;
     examples: any;
-})[];
-export = _exports;
+}[];
+/**
+ * @param operation Operation to retrieve requestBody examples for.
+ * @returns An object of response examples keyed by their media type.
+ */
+export default function getRequestBodyExamples(operation: RMOAS.OperationObject): RequestBodyExamples;

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

@@ -1,4 +1,4 @@
-declare function _exports(operation: any, oas: any, statusCode: string): {
+declare function _exports(operation: any, api: any, statusCode: any): {
     type: any;
     schema: any;
     label: string;

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

@@ -1,5 +1,10 @@
-declare function _exports(operation: object): (false | {
+import type * as RMOAS from '../rmoas.types';
+export declare type ResponseExamples = {
     status: string;
-    mediaTypes: {};
-})[];
-export = _exports;
+    mediaTypes: Record<string, RMOAS.MediaTypeObject>;
+}[];
+/**
+ * @param operation Operation to retrieve response examples for.
+ * @returns An object of response examples keyed by their media type.
+ */
+export default function getResponseExamples(operation: RMOAS.OperationObject): ResponseExamples;