oas 31.1.2 → 32.1.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { O as Operation, W as Webhook, E as Extensions } from './extensions-gq53-7Ux.js';
+import { PathsObject, HttpMethods, OASDocument, User, ServerVariable, ServerVariablesObject, Servers, AuthForHAR, SecuritySchemeObject, DataForHAR, SchemaObject, OAS31Document, OperationObject, SecurityRequirementObject, KeyedSecuritySchemeObject, SecurityType, TagObject, ParameterObject, SchemaWrapper, MediaTypeObject, ResponseObject, PathItemObject } from './types.js';
 import { Match, ParamData } from 'path-to-regexp';
-import { PathsObject, HttpMethods, OASDocument, User, ServerVariable, ServerVariablesObject, Servers, AuthForHAR } from './types.js';
+import { g as getParametersAsJSONSchemaOptions } from './get-parameters-as-json-schema-BH81ZOnw.js';
 import 'json-schema';
 import 'openapi-types';
 
@@ -19,7 +19,7 @@ type PathMatches = PathMatch[];
 
 declare class Oas {
     /**
-     * An OpenAPI API Definition.
+     * The current OpenAPI definition.
      */
     api: OASDocument;
     /**
@@ -44,6 +44,13 @@ declare class Oas {
         complete: boolean;
         processing: boolean;
     };
+    /**
+     * Have the component schemas within this API definition been decorated with our
+     * `x-readme-ref-name` extension?
+     *
+     * @see {@link decorateComponentSchemas}
+     */
+    protected schemasDecorated: boolean;
     /**
      * @param oas An OpenAPI definition.
      * @param user The information about a user that we should use when pulling auth tokens from
@@ -194,6 +201,26 @@ declare class Oas {
      * @param selectedApp The user app to retrieve an auth key for.
      */
     getAuth(user: User, selectedApp?: number | string): AuthForHAR;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: string): SecuritySchemeObject | undefined;
     /**
      * Returns the `paths` object that exists in this API definition but with every `method` mapped
      * to an instance of the `Operation` class.
@@ -256,6 +283,26 @@ declare class Oas {
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions}
      */
     validateExtensions(): void;
+    /**
+     * Dereference the current API definition so it can be parsed free from the hassle of resolving
+     * `$ref` schemas and circular structures.
+     *
+     */
+    dereference(opts?: {
+        /**
+         * A callback method can be supplied to be called when dereferencing is complete. Used for
+         * debugging that the multi-promise handling within this method works.
+         *
+         * @private
+         */
+        cb?: () => void;
+    }): Promise<(typeof this.promises)[] | boolean>;
+    /**
+     * Determine if the current API definition has been dereferenced or not.
+     *
+     * @see Oas.dereference
+     */
+    isDereferenced(): boolean;
     /**
      * Retrieve any circular `$ref` pointers that maybe present within the API definition.
      *
@@ -264,8 +311,527 @@ declare class Oas {
      * @see Oas.dereference
      */
     getCircularReferences(): string[];
+}
+
+interface MediaTypeExample {
+    description?: string;
+    summary?: string;
+    title?: string;
+    value: unknown;
+}
+
+interface ResponseExample {
+    mediaTypes: Record<string, MediaTypeExample[]>;
+    onlyHeaders?: boolean;
+    status: string;
+}
+
+interface CallbackExample {
+    example: ResponseExample[];
+    expression: string;
+    identifier: string;
+    method: string;
+}
+
+type ExampleGroups = Record<string, {
+    /**
+     * Array of custom code samples that contain `correspondingExample` key.
+     * Mutually exclusive of `request`. Note that if this object is present,
+     * there may or may not be corresponding responses in the `response` object.
+     */
+    customCodeSamples?: (NonNullable<Extensions['code-samples']>[number] & {
+        /**
+         * The index in the originally defined `code-samples` array
+         */
+        originalIndex: number;
+    })[];
+    /**
+     * Title of example group. This is derived from the `summary` field of one of
+     * the operation's example objects. The precedence is as follows (from highest to lowest):
+     * 1. The first custom code sample's `name` field.
+     * 2. The first request parameter (e.g., cookie/header/path/query) example object that
+     *  contains a `summary` field
+     * 3. The request body example object's `summary` field
+     * 4. The response example object's `summary` field
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#example-object}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#example-object}
+     */
+    name: string;
+    /**
+     * Object containing the example request data for the current example key.
+     * Mutually exclusive of `customCodeSamples`. If `customCodeSamples` is present,
+     * any request example definitions are ignored.
+     */
+    request?: DataForHAR;
+    /**
+     * Object containing the example response data for the current example key.
+     */
+    response?: {
+        /**
+         * The content type of the current example
+         *
+         * @example "application/json"
+         * @example "text/plain"
+         */
+        mediaType: string;
+        /**
+         * The entire response example object. The example value itself is contained
+         * within `value`.
+         *
+         * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#example-object}
+         * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#example-object}
+         */
+        mediaTypeExample: MediaTypeExample;
+        /**
+         * The HTTP status code for the current response example
+         *
+         * @example "2xx"
+         * @example "400"
+         */
+        status: string;
+    };
+}>;
+
+interface RequestBodyExample {
+    examples: MediaTypeExample[];
+    mediaType: string;
+}
+
+interface OperationIDGeneratorOptions {
+    /**
+     * Generate a JS method-friendly operation ID when one isn't present.
+     *
+     * For backwards compatiblity reasons this option will be indefinitely supported however we
+     * recommend using `friendlyCase` instead as it's a heavily improved version of this option.
+     *
+     * @see {friendlyCase}
+     * @deprecated
+     */
+    camelCase?: boolean;
+    /**
+     * Generate a human-friendly, but still camelCase, operation ID when one isn't present. The
+     * difference between this and `camelCase` is that this also ensure that consecutive words are
+     * not present in the resulting ID. For example, for the endpoint `/candidate/{candidate}` will
+     * return `getCandidateCandidate` for `camelCase` however `friendlyCase` will return
+     * `getCandidate`.
+     *
+     * The reason this friendliness is just not a part of the `camelCase` option is because we have
+     * a number of consumers of the old operation ID style and making that change there would a
+     * breaking change that we don't have any easy way to resolve.
+     */
+    friendlyCase?: boolean;
+}
+
+interface ResponseSchemaObject {
+    description?: string;
+    label: string;
+    schema: SchemaObject;
+    type: string[] | string;
+}
+
+declare class Operation {
+    /**
+     * The `Oas` instance that this operation belongs to.
+     */
+    oas: Oas;
+    /**
+     * Schema of the operation from the API Definition.
+     */
+    schema: OperationObject;
+    /**
+     * OpenAPI API Definition that this operation originated from.
+     */
+    api: OASDocument;
+    /**
+     * Path that this operation is targeted towards.
+     */
+    path: string;
+    /**
+     * HTTP Method that this operation is targeted towards.
+     */
+    method: HttpMethods;
+    /**
+     * The primary Content Type that this operation accepts.
+     */
+    contentType: string | undefined;
+    /**
+     * An object with groups of all example definitions (body/header/query/path/response/etc.)
+     */
+    exampleGroups: ExampleGroups | undefined;
+    /**
+     * Request body examples for this operation.
+     */
+    requestBodyExamples: RequestBodyExample[] | undefined;
+    /**
+     * Response examples for this operation.
+     */
+    responseExamples: ResponseExample[] | undefined;
+    /**
+     * Callback examples for this operation (if it has callbacks).
+     */
+    callbackExamples: CallbackExample[] | undefined;
+    /**
+     * Flattened out arrays of both request and response headers that are utilized on this operation.
+     */
+    headers: {
+        request: string[];
+        response: string[];
+    };
+    /**
+     * Internal storage array that the library utilizes to keep track of the times the
+     * {@see Operation.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.
+     */
+    protected promises: {
+        reject: any;
+        resolve: 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: {
+        circularRefs: string[];
+        complete: boolean;
+        processing: boolean;
+    };
+    /**
+     * Have the component schemas within this API definition been decorated with our
+     * `x-readme-ref-name` extension?
+     *
+     * @see {@link decorateComponentSchemas}
+     */
+    protected schemasDecorated: boolean;
+    constructor(oas: Oas, path: string, method: HttpMethods, operation: OperationObject);
+    /**
+     * Retrieve the `summary` for this operation.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationsummary}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-summary}
+     */
+    getSummary(): string | undefined;
+    /**
+     * Retrieve the `description` for this operation.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationdescription}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-description}
+     */
+    getDescription(): string | undefined;
+    /**
+     * Retrieve the primary content type for this operation. If multiple exist, the first JSON-like
+     * type will be returned.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-requestbodycontent}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-request-body-content}
+     */
+    getContentType(): string;
+    /**
+     * Checks if the current operation has a `x-www-form-urlencoded` content type payload.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-requestbodycontent}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-request-body-content}
+     */
+    isFormUrlEncoded(): boolean;
+    /**
+     * Checks if the current operation has a mutipart content type payload.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-requestbodycontent}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-request-body-content}
+     */
+    isMultipart(): boolean;
+    /**
+     * Checks if the current operation has a JSON-like content type payload.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-requestbodycontent}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-request-body-content}
+     */
+    isJson(): boolean;
+    /**
+     * Checks if the current operation has an XML content type payload.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-requestbodycontent}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-request-body-content}
+     */
+    isXml(): boolean;
+    /**
+     * Checks if the current operation is a webhook or not.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#oas-webhooks}
+     */
+    isWebhook(): boolean;
+    /**
+     * 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).
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-requirement-object}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#security-requirement-object}
+     */
+    getSecurity(): SecurityRequirementObject[];
+    /**
+     * Retrieve a collection of grouped security schemes. The inner array determines AND-grouped
+     * security schemes, the outer array determines OR-groups.
+     *
+     * @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}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#security-requirement-object}
+     * @param filterInvalid Optional flag that, when set to `true`, filters out invalid/nonexistent
+     *    security schemes, rather than returning `false`.
+     */
+    getSecurityWithTypes(filterInvalid?: boolean): ((false | {
+        security: KeyedSecuritySchemeObject;
+        type: SecurityType;
+    })[] | false)[];
+    /**
+     * Retrieve an object where the keys are unique scheme types, and the values are arrays
+     * containing each security scheme of that type.
+     *
+     */
+    prepareSecurity(): Record<SecurityType, KeyedSecuritySchemeObject[]>;
+    /**
+     * Retrieve all of the headers, request and response, that are associated with this operation.
+     *
+     */
+    getHeaders(): Operation['headers'];
+    /**
+     * Determine if this operation has an `operationId` present in its schema. Note that if one is
+     * present in the schema but is an empty string then this will return `false`.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationid}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-id}
+     */
+    hasOperationId(): boolean;
+    /**
+     * Determine if an operation has an `operationId` present in its schema. Note that if one is
+     * present in the schema but is an empty string then this will return `false`.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationid}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-id}
+     */
+    static hasOperationId(schema: OperationObject): boolean;
     /**
-     * Dereference the current OAS definition so it can be parsed free of worries of `$ref` schemas
+     * 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.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationid}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-id}
+     */
+    getOperationId(opts?: OperationIDGeneratorOptions): string;
+    /**
+     * Get an `operationId` for an operation. If one is not present (it's not required by the spec!)
+     * a hash of the path and method will be returned instead.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationid}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-id}
+     */
+    static getOperationId(path: string, method: string, schema: OperationObject, opts?: OperationIDGeneratorOptions): string;
+    /**
+     * Return an array of all tags, and their metadata, that exist on this operation.
+     *
+     */
+    getTags(): TagObject[];
+    /**
+     * Return is the operation is flagged as `deprecated` or not.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationdeprecated}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-deprecated}
+     */
+    isDeprecated(): boolean;
+    /**
+     * Determine if the operation has any (non-request body) parameters.
+     *
+     */
+    hasParameters(): boolean;
+    /**
+     * Return the parameters (non-request body) on the operation.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationparameters}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-parameters}
+     */
+    getParameters(): ParameterObject[];
+    /**
+     * Determine if this operation has any required parameters.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationparameters}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-parameters}
+     */
+    hasRequiredParameters(): boolean;
+    /**
+     * Convert the operation into an array of JSON Schema schemas for each available type of
+     * parameter available on the operation.
+     *
+     * Note that this method is not compatible with an operation or OpenAPI definition that has been
+     * processed with `.dereference()`. This method can only be called with the _original_ API
+     * definition that was used to initialize the `Operation` and `Oas` instance. If a dereferenced
+     * schema is present when this is called a `TypeError` will be thrown.
+     *
+     * @throws {TypeError} If the operation or OpenAPI definition has been run through `.dereference().`
+     *
+     */
+    getParametersAsJSONSchema(opts?: getParametersAsJSONSchemaOptions): SchemaWrapper[] | null;
+    /**
+     * Get a single response for this status code, formatted as JSON schema.
+     *
+     * Note that this method is not compatible with an operation or OpenAPI definition that has been
+     * processed with `.dereference()`. This method can only be called with the _original_ API
+     * definition that was used to initialize the `Operation` and `Oas` instance. If a dereferenced
+     * schema is present when this is called a `TypeError` will be thrown.
+     *
+     * @param statusCode Status code to pull a JSON Schema response for.
+     * @param opts Options for schema generation.
+     * @param opts.contentType Optional content-type to use. If specified and the response doesn't have
+     *   this content-type, the function will return null.
+     */
+    getResponseAsJSONSchema(statusCode: number | string, opts?: {
+        /**
+         * If you wish to include discriminator mapping `$ref` components alongside your
+         * `discriminator` in schemas. Defaults to `true`.
+         */
+        includeDiscriminatorMappingRefs?: boolean;
+        /**
+         * Optional content-type to use. If specified and the response doesn't have this content-type,
+         * the function will return null.
+         */
+        contentType?: string;
+    }): ResponseSchemaObject[] | null;
+    /**
+     * Get an array of all valid response status codes for this operation.
+     *
+     */
+    getResponseStatusCodes(): string[];
+    /**
+     * Retrieve an array of all content types that this operation can return.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#response-object}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#response-object}
+     */
+    getResponseContentTypes(): string[];
+    /**
+     * Determine if the operation has any request bodies.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationrequestbody}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-request-body}
+     */
+    hasRequestBody(): boolean;
+    /**
+     * Return the current `requestBody` object, dereferencing it in the process if it's a `$ref`
+     * pointer.
+     *
+     */
+    private getResolvedRequestBody;
+    /**
+     * Retrieve the list of all available media types that the operations request body can accept.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#media-type-object}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object}
+     */
+    getRequestBodyMediaTypes(): string[];
+    /**
+     * Determine if this operation has a required request body.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#media-type-object}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object}
+     */
+    hasRequiredRequestBody(): boolean;
+    /**
+     * Retrieve a specific request body content schema off this operation.
+     *
+     * If no media type is supplied this will return either the first available JSON-like request
+     * body, or the first available if there are no JSON-like media types present. When this return
+     * comes back it's in the form of an array with the first key being the selected media type,
+     * followed by the media type object in question.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#media-type-object}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object}
+     * @param mediaType Specific request body media type to retrieve if present.
+     */
+    getRequestBody(mediaType?: string): MediaTypeObject | false | [string, MediaTypeObject, ...string[]];
+    /**
+     * Retrieve an array of request body examples that this operation has.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#request-body-examples}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#request-body-examples}
+     */
+    getRequestBodyExamples(): RequestBodyExample[];
+    /**
+     * Return a specific response out of the operation by a given HTTP status code.
+     *
+     * @param statusCode Status code to pull a response object for.
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#response-object}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#response-object}
+     */
+    getResponseByStatusCode(statusCode: number | string): ResponseObject | false;
+    /**
+     * Retrieve an array of response examples that this operation has.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#response-object-examples}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#response-object-examples}
+     */
+    getResponseExamples(): ResponseExample[];
+    /**
+     * Determine if the operation has callbacks.
+     *
+     * @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#callback-object}
+     */
+    hasCallbacks(): boolean;
+    /**
+     * Retrieve a specific 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#callback-object}
+     * @param identifier Callback identifier to look for.
+     * @param expression Callback expression to look for.
+     * @param method HTTP Method on the callback to look for.
+     */
+    getCallback(identifier: string, expression: string, method: HttpMethods): Callback | false;
+    /**
+     * Retrieve an array of operations created from each 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#callback-object}
+     */
+    getCallbacks(): Callback[];
+    /**
+     * Retrieve an array of callback examples that this operation has.
+     *
+     * @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#callback-object}
+     */
+    getCallbackExamples(): CallbackExample[];
+    /**
+     * Determine if a given a custom specification extension exists within the operation.
+     *
+     * @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: string): boolean;
+    /**
+     * Retrieve a custom specification extension off of the operation.
+     *
+     * @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.
+     *
+     * @deprecated Use `oas.getExtension(extension, operation)` instead.
+     */
+    getExtension(extension: string | keyof Extensions): any;
+    /**
+     * Returns an object with groups of all example definitions (body/header/query/path/response/etc.).
+     * The examples are grouped by their key when defined via the `examples` map.
+     *
+     * Any custom code samples defined via the `x-readme.code-samples` extension are returned,
+     * regardless of if they have a matching response example.
+     *
+     * For standard OAS request parameter (e.g., body/header/query/path/etc.) examples,
+     * they are only present in the return object if they have a corresponding response example
+     * (i.e., a response example with the same key in the `examples` map).
+     */
+    getExampleGroups(): ExampleGroups;
+    /**
+     * Dereference the current operation schema so it can be parsed free of worries of `$ref` schemas
      * and circular structures.
      *
      */
@@ -277,11 +843,383 @@ declare class Oas {
          * @private
          */
         cb?: () => void;
+    }): Promise<(typeof this.promises)[] | boolean>;
+    /**
+     * Determine if the current operation schema, or the OpenAPI definition it's part of, has been
+     * dereferenced or not with `.dereference()`.
+     *
+     * @see Operation.dereference
+     */
+    isDereferenced(): boolean;
+    /**
+     * Retrieve any circular `$ref` pointers that maybe present within operation schema.
+     *
+     * This method requires that you first dereference the definition.
+     *
+     * @see Operation.dereference
+     */
+    getCircularReferences(): string[];
+}
+declare class Callback extends Operation {
+    /**
+     * The identifier that this callback is set to.
+     */
+    identifier: string;
+    /**
+     * The parent path item object that this Callback exists within.
+     */
+    parentSchema: PathItemObject;
+    constructor(oas: Oas, path: string, method: HttpMethods, operation: OperationObject, identifier: string, parentPathItem: PathItemObject);
+    /**
+     * 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#callback-object}
+     */
+    getIdentifier(): string;
+    /**
+     * Retrieve the `summary` for this callback.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationsummary}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-summary}
+     */
+    getSummary(): string | undefined;
+    /**
+     * Retrieve the `description` for this operation.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationdescription}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-description}
+     */
+    getDescription(): string | undefined;
+    /**
+     * Return the parameters (non-request body) on the operation.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationparameters}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-parameters}
+     */
+    getParameters(): ParameterObject[];
+}
+declare class Webhook extends Operation {
+    /**
+     * OpenAPI API Definition that this webhook originated from.
+     */
+    api: OAS31Document;
+    /**
+     * Retrieve the `summary` for this callback.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationsummary}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-summary}
+     */
+    getSummary(): string | undefined;
+    /**
+     * Retrieve the `description` for this operation.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationdescription}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-description}
+     */
+    getDescription(): string | undefined;
+}
+
+/**
+ * Enables custom-written code samples to be set for your operations. Use this if you have specific
+ * formatting that may not be followed by the auto-generated code samples. Custom code samples are
+ * treated as static content.
+ *
+ * This extension only be placed at the operation level.
+ *
+ * @defaultValue []
+ * @see {@link https://docs.readme.com/main/docs/openapi-extensions#custom-code-samples}
+ * @example
+ * {
+ *  "x-readme": {
+ *    "code-samples": [
+ *      {
+ *        "language": "curl",
+ *        "code": "curl -X POST https://api.example.com/v2/alert",
+ *        "name": "Custom cURL snippet",
+ *        "install": "brew install curl"
+ *      },
+ *      {
+ *        "language": "php",
+ *        "code": "<?php echo \"This is our custom PHP code snippet.\"; ?>",
+ *        "name": "Custom PHP snippet"
+ *      }
+ *    ]
+ *  }
+ * }
+ */
+declare const CODE_SAMPLES = "code-samples";
+/**
+ * Disables the API Explorer's "Try It" button, preventing users from making API requests from
+ * within your docs. Users will still be able to fill out any entry fields (path or query
+ * parameters, etc.), and code snippets will be auto-generated based on the user's input, however
+ * to interact with your API the user will need to copy the code snippet and execute it outside of
+ * your docs.
+ *
+ * This **does not** disable your API Reference documentation.
+ *
+ * @defaultValue true
+ * @see {@link https://docs.readme.com/main/docs/openapi-extensions#disable-the-api-explorer}
+ * @example
+ * {
+ *  "x-readme": {
+ *    "explorer-enabled": true
+ *  }
+ * }
+ */
+declare const EXPLORER_ENABLED = "explorer-enabled";
+/**
+ * Adds static headers to add to each request. Use this when there are specific headers unique to
+ * your API.
+ *
+ * @defaultValue []
+ * @see {@link https://docs.readme.com/main/docs/openapi-extensions#static-headers}
+ * @example
+ * {
+ *  "x-readme": {
+ *    "headers": [
+ *      {
+ *        "key": "X-Static-Header-One",
+ *        "value": "owlbert"
+ *      },
+ *      {
+ *        "key": "X-Static-Header-Two",
+ *        "value": "owlivia"
+ *      }
+ *    ]
+ *  }
+ * }
+ */
+declare const HEADERS = "headers";
+/**
+ * Allows you to mark an API endpoint, or _every_ API endpoint if defined in the root, as being
+ * internal and hidden from your public API reference.
+ *
+ * @defaultValue false
+ * @see {@link https://docs.readme.com/main/docs/openapi-extensions#internal}
+ * @example
+ * {
+ *  "x-internal": true
+ * }
+ * @example
+ * {
+ *  "x-readme": {
+ *    "internal": true
+ *  }
+ * }
+ */
+declare const INTERNAL = "internal";
+/**
+ * Disables API requests from the API Explorer's "Try It" button from being sent into our [API
+ * Metrics](https://readme.com/metrics) for you and your users. Additionally on any API endpoint
+ * that this is disabled on your users will not see lists or graphs of previous requests they've
+ * made against that API endpoint — either through the API Explorer's interactivity or through one
+ * of our [Metrics SDKs](https://docs.readme.com/main/docs/api-metrics-setup) (if you have those
+ * installed on your API).
+ *
+ * @defaultValue true
+ * @see {@link https://docs.readme.com/main/docs/openapi-extensions#disable-api-metrics}
+ * @example
+ * {
+ *  "x-readme": {
+ *    "metrics-defaults": false
+ *  }
+ * }
+ */
+declare const METRICS_ENABLED = "metrics-enabled";
+/**
+ * Configuration options for OAuth flows in the API Explorer.
+ *
+ * @defaultValue {}
+ * @see {@link https://docs.readme.com/main/docs/openapi-extensions#oauth-configuration-options}
+ * @example
+ * {
+ *  "x-readme": {
+ *    "oauth-options": {
+ *      "scopeSeparator": ",",
+ *      "useInsecureClientAuthentication": true,
+ *      "usePkce": false
+ *    }
+ *  }
+ * }
+ */
+declare const OAUTH_OPTIONS = "oauth-options";
+/**
+ * Controls the order of parameters on your API Reference pages.
+ *
+ * Your custom ordering **must** contain all of our available parameter types:
+ *
+ *  - `path`: Path parameters
+ *  - `query`: Query parameters
+ *  - `body`: Non-`application/x-www-form-urlencoded` request body payloads
+ *  - `cookie`: Cookie parameters
+ *  - `form`: `application/x-www-form-urlencoded` request body payloads
+ *  - `header`: Header parameters
+ *
+ * @defaultValue ['path', 'query', 'body', 'cookie', 'form', 'header']
+ * @see {@link https://docs.readme.com/main/docs/openapi-extensions#parameter-ordering}
+ * @example
+ * {
+ *  "x-readme": {
+ *    "parameter-ordering": ['path', 'query', 'header', 'cookie', 'body', 'form']
+ *  }
+ * }
+ */
+declare const PARAMETER_ORDERING = "parameter-ordering";
+/**
+ * Toggles the CORS proxy used when making API requests from within your docs (via the "Try It"
+ * button). If your API is already set up to return CORS headers, you can safely disable this
+ * feature.
+ *
+ * Disabling the CORS proxy will make the request directly from the user's browser and will prevent
+ * [Metrics](https://docs.readme.com/main/docs/getting-started-with-metrics) data from being logged
+ * by us unless [Metrics have already set up on your backend](https://docs.readme.com/main/docs/api-metrics-setup).
+ *
+ * @defaultValue true
+ * @see {@link https://docs.readme.com/main/docs/openapi-extensions#cors-proxy-enabled}
+ * @example
+ * {
+ *  "x-readme": {
+ *    "proxy-enabled": true
+ *  }
+ * }
+ */
+declare const PROXY_ENABLED = "proxy-enabled";
+/**
+ * Toggles what languages are shown by default for code samples in the API Explorer. This only
+ * affects what languages are initially shown to the user; if the user picks another language from
+ * the three-dot menu, that language and the respective auto-generated code snippet will also appear
+ * as an option in the API Explorer.
+ *
+ * @defaultValue ['shell', 'node', 'ruby', 'php', 'python', 'java', 'csharp']
+ * @see {@link https://docs.readme.com/main/docs/openapi-extensions#code-sample-languages}
+ * @example
+ * {
+ *  "x-readme": {
+ *    "samples-languages": ["shell", "node", "ruby", "javascript", "python"]
+ *  }
+ * }
+ */
+declare const SAMPLES_LANGUAGES = "samples-languages";
+/**
+ * Toggles if you will see code snippets for ReadMe's SDK code generator tool `api`.
+ *
+ * @defaultValue true
+ * @see {@link https://api.readme.dev}
+ * @example
+ * {
+ *  "x-readme": {
+ *    "simple-mode": false
+ *  }
+ * }
+ */
+declare const SIMPLE_MODE = "simple-mode";
+/**
+ * If `true`, tags are generated from the file top-down. If `false`, we sort the tags
+ * based off the `tags` array in the OAS file.
+ *
+ * @defaultValue false
+ * @see {@link https://docs.readme.com/main/docs/openapi-extensions#disable-tag-sorting}
+ * @example
+ * {
+ *  "x-readme": {
+ *    "disable-tag-sorting": true
+ *  }
+ * }
+ */
+declare const DISABLE_TAG_SORTING = "disable-tag-sorting";
+interface Extensions {
+    [CODE_SAMPLES]: {
         /**
-         * Preserve component schema names within themselves as a `title`.
+         * Custom code snippet
+         * @example "curl -X POST https://api.example.com/v2/alert"
          */
-        preserveRefAsJSONSchemaTitle?: boolean;
-    }): Promise<(typeof this.promises)[] | boolean>;
+        code: string;
+        /**
+         * Corresponding response example
+         * @see {@link https://docs.readme.com/main/docs/openapi-extensions#corresponding-response-examples}
+         */
+        correspondingExample?: string;
+        /**
+         * Library installation instructions
+         * @example "brew install httpie"
+         * @example "npm install node-fetch@2 --save"
+         */
+        install?: string;
+        /**
+         * Language for syntax highlighting
+         * @example shell
+         */
+        language: string;
+        /**
+         * Optional title for code sample
+         * @example "Custom cURL snippet"
+         */
+        name?: string;
+    }[] | undefined;
+    [DISABLE_TAG_SORTING]: boolean;
+    [EXPLORER_ENABLED]: boolean;
+    [HEADERS]: Record<string, number | string>[] | undefined;
+    [INTERNAL]: boolean;
+    [METRICS_ENABLED]: boolean;
+    [OAUTH_OPTIONS]: {
+        /**
+         * Scope separator for passing scopes. This value will be URL-encoded.
+         *
+         * @example ","
+         * @example "+"
+         * @default " "
+         * @see {@link https://datatracker.ietf.org/doc/html/rfc6749#section-3.3} Scope separators information from OAuth 2.0 specification
+         */
+        scopeSeparator?: string;
+        /**
+         * When enabled, the client credentials (i.e., `client_id` and `client_secret`) are sent in the request body (NOT recommended).
+         * When disabled (the default), client credentials are sent using the HTTP Basic Authentication scheme.
+         *
+         * This is applicable for all requests to the token endpoint.
+         *
+         * @see {@link https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1}
+         * @see {@link https://datatracker.ietf.org/doc/html/rfc6749#section-3.2}
+         *
+         * @example true
+         * @default false
+         */
+        useInsecureClientAuthentication?: boolean;
+        /**
+         * When enabled, uses PKCE (Proof Key for Code Exchange) for the authorization code flow.
+         * The client secret is replaced with an auto-generated code verifier and code challenge.
+         * When disabled, uses the standard OAuth 2.0 authorization code flow with client credentials.
+         *
+         * @see {@link https://datatracker.ietf.org/doc/html/rfc7636#section-4.1}
+         * @see {@link https://datatracker.ietf.org/doc/html/rfc7636#section-4.2}
+         *
+         * @example true
+         * @default false
+         */
+        usePkce?: boolean;
+    };
+    [PARAMETER_ORDERING]: ('body' | 'cookie' | 'form' | 'header' | 'path' | 'query')[];
+    [PROXY_ENABLED]: boolean;
+    [SAMPLES_LANGUAGES]: string[];
+    [SIMPLE_MODE]: boolean;
 }
+declare const extensionDefaults: Extensions;
+/**
+ * Determing if an OpenAPI definition has an extension set in its root schema.
+ *
+ */
+declare function hasRootExtension(extension: string | keyof Extensions, api: OASDocument): boolean;
+/**
+ * Retrieve a custom specification extension off of the API definition.
+ *
+ */
+declare function getExtension(extension: string | keyof Extensions, api: OASDocument, operation?: Operation): any;
+/**
+ * Validate that the data for an instanceof our `PARAMETER_ORDERING` extension is properly
+ * configured.
+ *
+ * @private
+ */
+declare function validateParameterOrdering(ordering: (typeof extensionDefaults)[typeof PARAMETER_ORDERING] | undefined, extension: string): void;
 
-export { Oas as default };
+export { Callback as C, DISABLE_TAG_SORTING as D, EXPLORER_ENABLED as E, HEADERS as H, INTERNAL as I, METRICS_ENABLED as M, Operation as O, PARAMETER_ORDERING as P, SAMPLES_LANGUAGES as S, Webhook as W, CODE_SAMPLES as a, type Extensions as b, OAUTH_OPTIONS as c, PROXY_ENABLED as d, Oas as default, SIMPLE_MODE as e, extensionDefaults as f, getExtension as g, hasRootExtension as h, validateParameterOrdering as v };