@microsoft/teams-js/dist/esm/packages/teams-js/dts/internal/utils.d.ts

Microsoft Client SDK for building app for Microsoft hosts

import { AdaptiveCardVersion, SdkError } from '../public/interfaces';
import * as pages from '../public/pages/pages';
import { IBaseRuntime } from '../public/runtime';
/**
 * @internal
 * Limited to Microsoft-internal use
 */
export declare function getGenericOnCompleteHandler(errorMessage?: string): (success: boolean, reason?: string) => void;
/**
 * @hidden
 * Compares SDK versions.
 *
 * @param v1 - first version
 * @param v2 - second version
 * @returns NaN in case inputs are not in right format
 *         -1 if v1 < v2
 *          1 if v1 > v2
 *          0 otherwise
 * @example
 *    compareSDKVersions('1.2', '1.2.0') returns 0
 *    compareSDKVersions('1.2a', '1.2b') returns NaN
 *    compareSDKVersions('1.2', '1.3') returns -1
 *    compareSDKVersions('2.0', '1.3.2') returns 1
 *    compareSDKVersions('2.0', 2.0) returns NaN
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export declare function compareSDKVersions(v1: string, v2: string): number;
/**
 * @hidden
 * Generates a GUID
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export declare function generateGUID(): string;
/**
 * @internal
 * Limited to Microsoft-internal use
 */
export declare function deepFreeze<T extends object>(obj: T): T;
/**
 * @hidden
 * The following type definitions will be used in the
 * utility functions below, which help in transforming the
 * promises to support callbacks for backward compatibility
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export type ErrorResultCallback<T> = (err?: SdkError, result?: T) => void;
export type ErrorResultNullCallback<T> = (err: SdkError | null, result: T | null) => void;
export type ErrorBooleanResultCallback = (err?: SdkError, result?: boolean) => void;
export type InputFunction<T> = (...args: any[]) => Promise<T>;
export type ResultCallback<T> = (result?: T) => void;
export type SdkErrorCallback = ResultCallback<SdkError | null>;
/**
 * This utility function is used when the result of the promise is same as the result in the callback.
 * @param funcHelper
 * @param callback
 * @param args
 * @returns
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export declare function callCallbackWithErrorOrResultFromPromiseAndReturnPromise<T>(funcHelper: InputFunction<T>, callback?: ErrorResultCallback<T>, ...args: any[]): Promise<T>;
/**
 * This utility function is used when the return type of the promise is usually void and
 * the result in the callback is a boolean type (true for success and false for error)
 * @param funcHelper
 * @param callback
 * @param args
 * @returns
 * @internal
 * Limited to Microsoft-internal use
 */
export declare function callCallbackWithErrorOrBooleanFromPromiseAndReturnPromise<T>(funcHelper: InputFunction<T>, callback?: ErrorBooleanResultCallback, ...args: any[]): Promise<T>;
/**
 * This utility function is called when the callback has only Error/SdkError as the primary argument.
 * @param funcHelper
 * @param callback
 * @param args
 * @returns
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export declare function callCallbackWithSdkErrorFromPromiseAndReturnPromise<T>(funcHelper: InputFunction<T>, callback?: SdkErrorCallback, ...args: any[]): Promise<T>;
/**
 * This utility function is used when the result of the promise is same as the result in the callback.
 * @param funcHelper
 * @param callback
 * @param args
 * @returns
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export declare function callCallbackWithErrorOrResultOrNullFromPromiseAndReturnPromise<T>(funcHelper: InputFunction<T>, callback?: ErrorResultNullCallback<T>, ...args: any[]): Promise<T>;
/**
 * A helper function to add a timeout to an asynchronous operation.
 *
 * @param action Action to wrap the timeout around
 * @param timeoutInMs Timeout period in milliseconds
 * @param timeoutError Error to reject the promise with if timeout elapses before the action completed
 * @returns A promise which resolves to the result of provided action or rejects with a provided timeout error
 * if the initial action didn't complete within provided timeout.
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export declare function runWithTimeout<TResult, TError>(action: () => Promise<TResult>, timeoutInMs: number, timeoutError: TError): Promise<TResult>;
/**
 * @internal
 * Limited to Microsoft-internal use
 */
export declare function createTeamsAppLink(params: pages.AppNavigationParameters): string;
/**
 * @hidden
 * Checks if the Adaptive Card schema version is supported by the host.
 * @param hostAdaptiveCardSchemaVersion Host's supported Adaptive Card version in the runtime.
 *
 * @returns true if the Adaptive Card Version is not supported and false if it is supported.
 */
export declare function isHostAdaptiveCardSchemaVersionUnsupported(hostAdaptiveCardSchemaVersion: AdaptiveCardVersion): boolean;
/**
 * @hidden
 * Checks if a URL is a HTTPS protocol based URL.
 * @param url URL to be validated.
 *
 * @returns true if the URL is an https URL.
 */
export declare function isValidHttpsURL(url: URL): boolean;
/**
 * Convert base64 string to blob
 * @param base64Data string respresenting the content
 * @param contentType Mimetype
 * @returns Promise
 */
export declare function base64ToBlob(mimeType: string, base64String: string): Promise<Blob>;
/**
 * Converts blob to base64 string.
 * @param blob Blob to convert to base64 string.
 */
export declare function getBase64StringFromBlob(blob: Blob): Promise<string>;
/**
 *  Returns an SSR safe reference to the window object
 * @returns Window object reference
 */
export declare function ssrSafeWindow(): Window;
/**
 * Checks if running in a Server Side Environment
 * @returns True if running in a Server Side Environment
 */
export declare function inServerSideRenderingEnvironment(): boolean;
/**
 * @param id The id to validate
 * @param errorToThrow Customized error to throw if the id is not valid
 *
 * @throws Error if id is not valid
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export declare function validateId(id: string, errorToThrow?: Error): void;
export declare function validateUrl(url: URL, errorToThrow?: Error): void;
/**
 * This function takes in a string that represents a full or relative path and returns a
 * fully qualified URL object.
 *
 * Currently this is accomplished by assigning the input string to an a tag and then retrieving
 * the a tag's href value. A side effect of doing this is that the string becomes a fully qualified
 * URL. This is probably not how I would choose to do this, but in order to not unintentionally
 * break something I've preseved the functionality here and just isolated the code to make it
 * easier to mock.
 *
 * @example
 *    `fullyQualifyUrlString('https://example.com')` returns `new URL('https://example.com')`
 *    `fullyQualifyUrlString('helloWorld')` returns `new URL('https://example.com/helloWorld')`
 *    `fullyQualifyUrlString('hello%20World')` returns `new URL('https://example.com/hello%20World')`
 *
 * @param fullOrRelativePath A string representing a full or relative URL.
 * @returns A fully qualified URL representing the input string.
 */
export declare function fullyQualifyUrlString(fullOrRelativePath: string): URL;
/**
 * Detects if there are any script tags in a given string, even if they are Uri encoded or encoded as HTML entities.
 * @param input string to test for script tags
 * @returns true if the input string contains a script tag, false otherwise
 */
export declare function hasScriptTags(input: string): boolean;
/**
 * @param id The ID to validate against the UUID format
 * @throws Error if ID is not a valid UUID
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export declare function validateUuid(id: string | undefined | null): void;
/**
 * @internal
 * Limited to Microsoft-internal use
 * @returns current timestamp in milliseconds
 */
export declare function getCurrentTimestamp(): number | undefined;
/**
 * @hidden
 * @internal
 * Limited to Microsoft-internal use
 *
 * Function to check whether the data is a primitive type or a plain object.
 * Recursion is limited to a maximum depth of 1000 to prevent excessive nesting and potential stack overflow.
 *
 * @param value The value to check
 * @returns true if the value is a primitive type or a plain object, false otherwise
 *
 */
export declare function isPrimitiveOrPlainObject(value: unknown, depth?: number): boolean;
/**
 * Normalizes legacy ageGroup values for backward compatibility
 * @param runtimeConfig - The runtime configuration object to normalize
 * @returns A new IBaseRuntime object with normalized ageGroup values
 */
export declare function normalizeAgeGroupValue(runtimeConfig: IBaseRuntime): IBaseRuntime;