@azure/core-client 1.3.3 → 1.4.0-alpha.20220104.5

package/types/latest/core-client.d.ts

@@ -1,4 +1,5 @@
 import { AbortSignalLike } from '@azure/abort-controller';
+import { AuthorizeRequestOnChallengeOptions } from '@azure/core-rest-pipeline';
 import { HttpClient } from '@azure/core-rest-pipeline';
 import { HttpMethods } from '@azure/core-rest-pipeline';
 import { InternalPipelineOptions } from '@azure/core-rest-pipeline';
@@ -11,6 +12,37 @@ import { PipelineResponse } from '@azure/core-rest-pipeline';
 import { TokenCredential } from '@azure/core-auth';
 import { TransferProgressEvent } from '@azure/core-rest-pipeline';
 
+/**
+ * This function can be used as a callback for the `bearerTokenAuthenticationPolicy` of `@azure/core-rest-pipeline`, to support CAE challenges:
+ * [Continuous Access Evaluation](https://docs.microsoft.com/azure/active-directory/conditional-access/concept-continuous-access-evaluation).
+ *
+ * Call the `bearerTokenAuthenticationPolicy` with the following options:
+ *
+ * ```ts
+ * import { bearerTokenAuthenticationPolicy } from "@azure/core-rest-pipeline";
+ * import { authorizeRequestOnClaimChallenge } from "@azure/core-client";
+ *
+ * const bearerTokenAuthenticationPolicy = bearerTokenAuthenticationPolicy({
+ *   authorizeRequestOnChallenge: authorizeRequestOnClaimChallenge
+ * });
+ * ```
+ *
+ * Once provided, the `bearerTokenAuthenticationPolicy` policy will internally handle Continuous Access Evaluation (CAE) challenges.
+ * When it can't complete a challenge it will return the 401 (unauthorized) response from ARM.
+ *
+ * Example challenge with claims:
+ *
+ * ```
+ * Bearer authorization_uri="https://login.windows-ppe.net/", error="invalid_token",
+ * error_description="User session has been revoked",
+ * claims="eyJhY2Nlc3NfdG9rZW4iOnsibmJmIjp7ImVzc2VudGlhbCI6dHJ1ZSwgInZhbHVlIjoiMTYwMzc0MjgwMCJ9fX0="
+ * ```
+ */
+export declare function authorizeRequestOnClaimChallenge(onChallengeOptions: AuthorizeRequestOnChallengeOptions): Promise<boolean>;
+
+/**
+ * The base definition of a mapper. Can be used for XML and plain JavaScript objects.
+ */
 export declare interface BaseMapper {
     /**
      * Name for the xml element
@@ -84,18 +116,47 @@ export declare interface CommonClientOptions extends PipelineOptions {
     allowInsecureConnection?: boolean;
 }
 
+/**
+ * A mapper composed of other mappers.
+ */
 export declare interface CompositeMapper extends BaseMapper {
+    /**
+     * The type descriptor of the `CompositeMapper`.
+     */
     type: CompositeMapperType;
 }
 
+/**
+ * Helps build a mapper that describes how to map a set of properties of an object based on other mappers.
+ *
+ * Only one of the following properties should be present: `className`, `modelProperties` and `additionalProperties`.
+ */
 export declare interface CompositeMapperType {
+    /**
+     * Name of the composite mapper type.
+     */
     name: "Composite";
+    /**
+     * Use `className` to reference another type definition.
+     */
     className?: string;
+    /**
+     * Use `modelProperties` when the reference to the other type has been resolved.
+     */
     modelProperties?: {
         [propertyName: string]: Mapper;
     };
+    /**
+     * Used when a model has `additionalProperties: true`. Allows the generic processing of unnamed model properties on the response object.
+     */
     additionalProperties?: Mapper;
+    /**
+     * The name of the top-most parent scheme, the one that has no parents.
+     */
     uberParent?: string;
+    /**
+     * A polymorphic discriminator.
+     */
     polymorphicDiscriminator?: PolymorphicDiscriminator;
 }
 
@@ -162,22 +223,55 @@ export declare interface DeserializationPolicyOptions {
     serializerOptions?: SerializerOptions;
 }
 
+/**
+ * A mapper describing plain JavaScript objects used as key/value pairs.
+ */
 export declare interface DictionaryMapper extends BaseMapper {
+    /**
+     * The type descriptor of the `DictionaryMapper`.
+     */
     type: DictionaryMapperType;
+    /**
+     * Optionally, a prefix to add to the header collection.
+     */
     headerCollectionPrefix?: string;
 }
 
+/**
+ * Helps build a mapper that describes how to parse a dictionary of mapped values.
+ */
 export declare interface DictionaryMapperType {
+    /**
+     * Name of the sequence type mapper.
+     */
     name: "Dictionary";
+    /**
+     * The mapper to use to map the value of each property in the dictionary.
+     */
     value: Mapper;
 }
 
+/**
+ * A mapper describing an enum value.
+ */
 export declare interface EnumMapper extends BaseMapper {
+    /**
+     * The type descriptor of the `EnumMapper`.
+     */
     type: EnumMapperType;
 }
 
+/**
+ * Helps build a mapper that describes how to parse an enum value.
+ */
 export declare interface EnumMapperType {
+    /**
+     * Name of the enum type mapper.
+     */
     name: "Enum";
+    /**
+     * Values allowed by this mapper.
+     */
     allowedValues: any[];
 }
 
@@ -225,22 +319,65 @@ export declare interface InternalClientPipelineOptions extends InternalPipelineO
     serializationOptions?: SerializationPolicyOptions;
 }
 
+/**
+ * Mappers are definitions of the data models used in the library.
+ * These data models are part of the Operation or Client definitions in the responses or parameters.
+ */
 export declare type Mapper = BaseMapper | CompositeMapper | SequenceMapper | DictionaryMapper | EnumMapper;
 
+/**
+ * Description of various value constraints such as integer ranges and string regex.
+ */
 export declare interface MapperConstraints {
+    /**
+     * The value should be less than or equal to the `InclusiveMaximum` value.
+     */
     InclusiveMaximum?: number;
+    /**
+     * The value should be less than the `ExclusiveMaximum` value.
+     */
     ExclusiveMaximum?: number;
+    /**
+     * The value should be greater than or equal to the `InclusiveMinimum` value.
+     */
     InclusiveMinimum?: number;
+    /**
+     * The value should be greater than the `InclusiveMinimum` value.
+     */
     ExclusiveMinimum?: number;
+    /**
+     * The length should be smaller than the `MaxLength`.
+     */
     MaxLength?: number;
+    /**
+     * The length should be bigger than the `MinLength`.
+     */
     MinLength?: number;
+    /**
+     * The value must match the pattern.
+     */
     Pattern?: RegExp;
+    /**
+     * The value must contain fewer items than the MaxItems value.
+     */
     MaxItems?: number;
+    /**
+     * The value must contain more items than the `MinItems` value.
+     */
     MinItems?: number;
+    /**
+     * The value must contain only unique items.
+     */
     UniqueItems?: true;
+    /**
+     * The value should be exactly divisible by the `MultipleOf` value.
+     */
     MultipleOf?: number;
 }
 
+/**
+ * Type of the mapper. Includes known mappers.
+ */
 export declare type MapperType = SimpleMapperType | CompositeMapperType | SequenceMapperType | DictionaryMapperType | EnumMapperType;
 
 /**
@@ -504,9 +641,25 @@ export declare type ParameterPath = string | string[] | {
     [propertyName: string]: ParameterPath;
 };
 
+/**
+ * Used to disambiguate discriminated type unions.
+ * For example, if response can have many shapes but also includes a 'kind' field (or similar),
+ * that field can be used to determine how to deserialize the response to the correct type.
+ */
 export declare interface PolymorphicDiscriminator {
+    /**
+     * Name of the discriminant property in the original JSON payload, e.g. `@odata.kind`.
+     */
     serializedName: string;
+    /**
+     * Name to use on the resulting object instead of the original property name.
+     * Useful since the JSON property could be difficult to work with.
+     * For example: For a field received as `@odata.kind`, the final object could instead include a property simply named `kind`.
+     */
     clientName: string;
+    /**
+     * It may contain any other property.
+     */
     [key: string]: string;
 }
 
@@ -522,12 +675,27 @@ export declare type QueryCollectionFormat = "CSV" | "SSV" | "TSV" | "Pipes" | "M
  */
 export declare type RawResponseCallback = (rawResponse: FullOperationResponse, flatResponse: unknown) => void;
 
+/**
+ * A mapper describing arrays.
+ */
 export declare interface SequenceMapper extends BaseMapper {
+    /**
+     * The type descriptor of the `SequenceMapper`.
+     */
     type: SequenceMapperType;
 }
 
+/**
+ * Helps build a mapper that describes how to parse a sequence of mapped values.
+ */
 export declare interface SequenceMapperType {
+    /**
+     * Name of the sequence type mapper.
+     */
     name: "Sequence";
+    /**
+     * The mapper to use to map each one of the properties of the sequence.
+     */
     element: Mapper;
 }
 
@@ -558,16 +726,46 @@ export declare interface SerializationPolicyOptions {
 
 /**
  * Used to map raw response objects to final shapes.
- * Mostly useful for unpacking/packing Dates and other encoded types that
- * are not intrinsic to JSON.
+ * Helps packing and unpacking Dates and other encoded types that are not intrinsic to JSON.
+ * Also allows pulling values from headers, as well as inserting default values and constants.
  */
 export declare interface Serializer {
+    /**
+     * The provided model mapper.
+     */
     readonly modelMappers: {
         [key: string]: any;
     };
+    /**
+     * Whether the contents are XML or not.
+     */
     readonly isXML: boolean;
+    /**
+     * Validates constraints, if any. This function will throw if the provided value does not respect those constraints.
+     * @param mapper - The definition of data models.
+     * @param value - The value.
+     * @param objectName - Name of the object. Used in the error messages.
+     */
     validateConstraints(mapper: Mapper, value: any, objectName: string): void;
+    /**
+     * Serialize the given object based on its metadata defined in the mapper.
+     *
+     * @param mapper - The mapper which defines the metadata of the serializable object.
+     * @param object - A valid Javascript object to be serialized.
+     * @param objectName - Name of the serialized object.
+     * @param options - additional options to deserialization.
+     * @returns A valid serialized Javascript object.
+     */
     serialize(mapper: Mapper, object: any, objectName?: string, options?: SerializerOptions): any;
+    /**
+     * Deserialize the given object based on its metadata defined in the mapper.
+     *
+     * @param mapper - The mapper which defines the metadata of the serializable object.
+     * @param responseBody - A valid Javascript entity to be deserialized.
+     * @param objectName - Name of the deserialized object.
+     * @param options - Controls behavior of XML parser and builder.
+     * @returns A valid deserialized Javascript object.
+     */
     deserialize(mapper: Mapper, responseBody: any, objectName: string, options?: SerializerOptions): any;
 }
 
@@ -654,7 +852,13 @@ export declare interface ServiceClientOptions extends CommonClientOptions {
     pipeline?: Pipeline;
 }
 
+/**
+ * The type of a simple mapper.
+ */
 export declare interface SimpleMapperType {
+    /**
+     * Name of the type of the property.
+     */
     name: "Base64Url" | "Boolean" | "ByteArray" | "Date" | "DateTime" | "DateTimeRfc1123" | "Object" | "Stream" | "String" | "TimeSpan" | "UnixTime" | "Uuid" | "Number" | "any";
 }