@dynatrace-sdk/client-query 1.15.0 → 1.17.0

package/types/packages/shared-errors/src/client-request-error.d.ts

@@ -1,10 +1,39 @@
 import { HttpClientResponse } from '@dynatrace-sdk/http-client';
 import { ApiClientError } from './api-client-error';
 import { ErrorResponseBody } from './types';
+/**
+ * Generic error class for service errors, used to handle both expected and unexpected service-level errors.
+ * @example Handling unexpected error response, received by the SDK Client
+ * const responseValue = await response.body('json');
+ *
+ * throw new ClientRequestError(
+ *   `${response.status}`,
+ *   response,
+ *   responseValue,
+ *   getErrorMessage(
+ *     responseValue,
+ *     `Unexpected api response: code=${response.status} body="${responseValue}"`,
+ *   ),
+ *   e,
+ * );
+ *
+ */
 export declare class ClientRequestError<DTO = ErrorResponseBody> extends ApiClientError {
     readonly isClientRequestError = true;
     body: DTO;
     response: HttpClientResponse;
     constructor(name: string, response: HttpClientResponse, body: DTO, message?: string, cause?: any);
 }
+/**
+ * ClientRequestError type guard function.
+ * Does a structural check of the passed object.
+ * @example
+ * try {
+ *   doSomething();
+ * } catch (e: unknown) {
+ *   if(isClientRequestError(e)) {
+ *     handleTheError();
+ *   }
+ * }
+ */
 export declare function isClientRequestError(e: any): e is ClientRequestError;

package/types/packages/shared-errors/src/index.d.ts

@@ -2,5 +2,4 @@ export * from './api-client-error';
 export * from './api-gateway-error';
 export * from './client-request-error';
 export * from './invalid-response-error';
-export * from './sdk-error';
 export * from './types';

package/types/packages/shared-errors/src/invalid-response-error.d.ts

@@ -1,9 +1,26 @@
 import { ApiClientError } from './api-client-error';
+/**
+ * Dedicated error class for errors related to response serialization.
+ * Thrown when received service response can't be deserialized.
+ **/
 export declare class InvalidResponseError extends ApiClientError {
     readonly isInvalidResponseError = true;
     responseBody: any;
     expectedType?: string;
     nestedError?: Error;
-    constructor(name: string, nestedError: Error | any | undefined, body: any, expectedType?: string, message?: string);
+    response: any;
+    constructor(name: string, nestedError: Error | any | undefined, body: any, expectedType?: string, message?: string, response?: any);
 }
+/**
+ * InvalidResponseError type guard function.
+ * Does a structural check of the passed object.
+ * @example
+ * try {
+ *    doSomething();
+ * } catch (e: unknown) {
+ *    if (isInvalidResponseError(e)) {
+ *      throw e;
+ *    }
+ * }
+ */
 export declare function isInvalidResponseError(e: any): e is InvalidResponseError;

package/types/packages/shared-errors/src/types.d.ts

@@ -1,31 +1,88 @@
-/**
- * Possible serialized error types
- * `COMMON`: Common JS error
- * `HTTP`: Error thrown by a http-client
- */
+/** @ignore*/
 export declare enum ErrorType {
     COMMON = "JS Error",
     HTTP = "Http Error"
 }
+/**
+ * Basic error envelope, that enforces all error to have mandatory "error" property.
+ * */
 export interface ErrorResponseBody<T = CommonApiError> {
+    /**
+     * *error* object must have two mandatory fields (*code, message*) and may have two additional fields (*help, details*):
+     * refer to the *CommonApiError* for more details.
+     * */
     error: T;
 }
+/**
+ * Common API error structure, established by Dynatrace API guidelines.
+ * */
 export interface CommonApiError<T extends Record<string, any> = Record<string, any>> {
+    /** The error code should be set to the HTTP error code by default.<br>
+     * The error code may be set to an API-specific error code which must be properly documented.*/
     code: number;
+    /** The error message should be short and precise, it should not contain details.*/
     message: string;
+    /**
+     * An additional help field may be added which must be a URL to further information on how to deal with the error.<br>
+     * This may be some detailed error documentation page or a link to the Dynatrace support system, etc.
+     * */
     help?: string;
+    /**
+     * Additional details about the error may be added in a details field.
+     * Refer to *CommonErrorDetails*
+     * */
     details?: T;
 }
+/**
+ * *CommonApiError* details object reference. Contains common API error information.
+ *  This object is used to convey additional information about the error like e.g., which query parameter exactly violated a precondition. <br>
+ *  Details may contain any fields to further describe the error
+ * */
 export interface CommonErrorDetails {
+    /**
+     * UUID string that represents a reference of the error into e.g., the log file of the service.
+     * */
     errorRef?: string;
+    /**
+     * String containing a 32-character hex integer value that is used for tracing.
+     * */
     traceId?: string;
+    /**
+     * String value representing a more detailed error information than the http response code alone.
+     * Must be a single word in CamelCase, and all possible values must be documented.
+     * */
     errorCode?: string;
+    /**
+     * An array of *ConstraintViolation* object, refer to ConstraintViolation object reference for more details.
+     * */
     constraintViolations?: ConstraintViolation[];
+    /**
+     * Must be an array of strings containing a complete list of missing IAM scopes necessary to successfully execute the request.
+     * Should be set if the API returns a 403 - Forbidden response in case of missing OAuth scopes.
+     * */
     missingScopes?: string[];
+    /**
+     * Must be an array of strings containing a complete list of missing IAM permissions necessary to successfully execute the request.
+     * Should be set if the API returns a 403 - Forbidden response in case of missing OAuth user permissions.
+     * */
     missingPermissions?: string[];
 }
+/**
+ * Contains information about an input parameter (path, query or request body)
+ * that violated some validation rule of the service API and caused the warning.<br>
+ * May contain additional fields further describing the warning.
+ * */
 export interface ConstraintViolation extends Record<string, string | undefined> {
+    /**
+     * Mandatory field message describing the warning.
+     * */
     message: string;
+    /**
+     * Describes the general location of the violating parameter (query parameter, request body, etc.)
+     */
     parameterLocation?: string;
+    /**
+     * Refers to the violating parameter within the parameterLocation.
+     */
     path?: string;
 }

package/types/packages/shared-errors/src/sdk-error.d.ts

@@ -1,5 +0,0 @@
-export declare class SDKError extends Error {
-    cause?: Error | undefined;
-    name: string;
-    constructor(message: string, cause?: Error | undefined);
-}