diff --git a/types/office-runtime/index.d.ts b/types/office-runtime/index.d.ts index 1b12464982..70153c4adc 100644 --- a/types/office-runtime/index.d.ts +++ b/types/office-runtime/index.d.ts @@ -3,111 +3,194 @@ // Definitions by: Michael Zlatskovsky , Michelle Scharlock // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped // Typescript Version: 2.4 - /* office-runtime Copyright (c) Microsoft Corporation */ - /** * Office runtime namespace. */ declare namespace OfficeRuntime { + /** + * Method that enables a pop up web dialog box. + * @param url Must be a string. + * @param options Optional parameter. Must be of type DisplayWebDialogOptions. + */ + function displayWebDialog(url: string, options?: DisplayWebDialogOptions): Promise; + /** + * Asynchronous, global, and persistent key-value storage. + */ + const storage: Storage; + /** + * Asynchronous, global, and persistent key-value storage. + * @remarks + * Storage limit is 10 MB per domain, which may be shared by multiple add-ins. + */ + interface Storage { /** - * Method that enables a pop up web dialog box. - * @param url Must be a string. - * @param options Optional parameter. Must be of type DisplayWebDialogOptions. + * Retrieves an item from storage based on its key. + * Returns a Promise. In the event the Promise does not resolve, returns null. + * @param key Key of item to be retrieved. Must be a string. */ - function displayWebDialog(url: string, options?: DisplayWebDialogOptions): Promise; + getItem(key: string): Promise; /** - * Asynchronous, global, and persistent key-value storage. + * Sets a key-value pair into storage or updates an existing key-value pair. + * Returns a Promise. + * @param key Key of item to be set. Must be a string. + * @param value Must be a string. */ - const storage: Storage; + setItem(key: string, value: string): Promise; + /** + * Removes an item from storage based on its key. + * Returns a Promise. + * @param key Key of item to be removed. Must be a string. + */ + removeItem(key: string): Promise; + /** + * Retrieves multiple items from storage based on their key. + * Returns a Promise. In the event the Promise does not resolve, returns null. + * @param keys Keys of items to be removed. Must be an array of strings. + */ + getItems(keys: string[]): Promise<{ [key: string]: string | null }>; + /** + * Sets multiple items into storage or updates multiple items within storage. + * Returns a Promise. + * @param keyValues Key-value pairs to be set. Must be strings. + */ + setItems(keyValues: { [key: string]: string }): Promise; + /** + * Removes multiple items from storage. + * Returns a Promise. + * @param keys Keys of items to be removed. Must be an array of strings. + */ + removeItems(keys: string[]): Promise; + /** + * Retrieves an array of all keys from storage. + * Returns a Promise. + */ + getKeys(): Promise; + } + /** Object representing the dialog box. */ + interface Dialog { + /** Method to close a dialog box. Returns a Promise. */ + close(): Promise; + } + /** Provides display options and actions a dialog box may take. */ + interface DisplayWebDialogOptions { + /** + * Optional parameter that determines whether the dialog box displays as a popup (false) or within an IFrame (true). + * This setting is only applicable to custom functions running on Excel Online. + */ + displayInIFrame?: boolean; + /** + * Optional parameter that defines the height of the dialog box as a percentage of the current display. + * For example, accepts strings such as: '50%', '50'. + */ + height?: string; + /** + * Optional parameter that defines the width of dialog as a percentage of window. + * For example, accepts strings such as: '50%', '50'. + */ + width?: string; + /** + * Optional callback that runs when the dialog box sends a message to its parent. + */ + onMessage?: (message: string, dialog?: Dialog) => void; + /** + * Optional callback that runs when the dialog box is closed. + */ + onClose?: () => void; + /** + * Optional callback that runs when the dialog box sends an error. + */ + onRuntimeError?: (error: Error, dialog?: Dialog) => void; + } + /** + * Contains authorization related APIs. + * @beta + */ + const auth: Auth; + /** + * Provides options for the user experience when Office obtains an access token to the add-in from AAD v. 2.0 with the getAccessToken method. + * @beta + */ + interface AuthOptions { + /** + * Allows Office to get an access token silectly or through interactive consent, if one is required. + * If set to false, Office will silently try to get an access token. If it fails to do so, Office will return a descriptive error. + * If set to true, Office will show an interactive consent UI after it fails to silently get an access token. + * The prompt will only allow consent to the AAD profile scope, not to any Microsoft Graph scopes. + */ + allowConsentPrompt?: boolean; + /** + * Allows Office to get an access token silently provided consent is present or show interactive UI to sign in the user. + * If set to false, office will silently try to get an access token. If it fails to do so, Office will return a descriptive error. + * If set to true, Office will show an interactive sign-in UI after it fails to silently get an access token. + */ + allowSignInPrompt?: boolean; + /** + * Deprecated + * Prompts the user to add their Office account (or to switch to it, if it is already added). + */ + forceAddAccount?: boolean; /** - * Asynchronous, global, and persistent key-value storage. + * Causes Office to prompt the user to provide the additional factor when the tenancy being targeted by Microsoft Graph requires multifactor + * authentication. The string value identifies the type of additional factor that is required. In most cases, you won't know at development + * time whether the user's tenant requires an additional factor or what the string should be. So this option would be used in a "second try" + * call of getAccessToken after Microsoft Graph has sent an error requesting the additional factor and containing the string that should + * be used with the authChallenge option. + */ + authChallenge?: string; + /** + * A user-defined item of any type that is returned, unchanged, in the asyncContext property of the AsyncResult object that is passed to a callback. + */ + asyncContext?: any; + /** + * Causes Office to return descriptive error when the add-in wants to access MS Graph and the user/admin has not granted consent to MS Graph scopes. + * Office only supports consent to graph scopes when the add-in has been deployed by a tenant admin. This information will not be available during development. + * Setting this option to true will allow Office to inform your add-in beforehand if MS graph access will fail by returning back a descriptive error. + */ + forMSGraphAccess?: boolean; + } + /** + * Interface that contains authorization related APIs. + * @beta + */ + interface Auth { + /** + * Calls the Azure Active Directory V 2.0 endpoint to get an access token to your add-in's web application. Enables add-ins to identify users. + * Server side code can use this token to access Microsoft Graph for the add-in's web application by using the + * {@link https://docs.microsoft.com/azure/active-directory/develop/active-directory-v2-protocols-oauth-on-behalf-of | "on behalf of" OAuth flow}. + * This API requires a single sign-on configuration that bridges the add-in to an Azure application. Office users sign-in with Organizational + * Accounts and Microsoft Accounts. Microsoft Azure returns tokens intended for both user account types to access resources in the Microsoft Graph. + * + * Important: In Outlook, this API is not supported if the add-in is loaded in an Outlook.com or Gmail mailbox. + * * @remarks - * Storage limit is 10 MB per domain, which may be shared by multiple add-ins. + * + * **Hosts**: Excel, PowerPoint, Word + * + * @beta + * + * @param options - Optional. Accepts an AuthOptions object to define sign-on behaviors. + * returns: Promise to the access token. */ - interface Storage { - /** - * Retrieves an item from storage based on its key. - * Returns a Promise. In the event the Promise does not resolve, returns null. - * @param key Key of item to be retrieved. Must be a string. - */ - getItem(key: string): Promise; - /** - * Sets a key-value pair into storage or updates an existing key-value pair. - * Returns a Promise. - * @param key Key of item to be set. Must be a string. - * @param value Must be a string. - */ - setItem(key: string, value: string): Promise; - /** - * Removes an item from storage based on its key. - * Returns a Promise. - * @param key Key of item to be removed. Must be a string. - */ - removeItem(key: string): Promise; - /** - * Retrieves multiple items from storage based on their key. - * Returns a Promise. In the event the Promise does not resolve, returns null. - * @param keys Keys of items to be removed. Must be an array of strings. - */ - getItems(keys: string[]): Promise<{ [key: string]: string | null }>; - /** - * Sets multiple items into storage or updates multiple items within storage. - * Returns a Promise. - * @param keyValues Key-value pairs to be set. Must be strings. - */ - setItems(keyValues: { [key: string]: string }): Promise; - /** - * Removes multiple items from storage. - * Returns a Promise. - * @param keys Keys of items to be removed. Must be an array of strings. - */ - removeItems(keys: string[]): Promise; - /** - * Retrieves an array of all keys from storage. - * Returns a Promise. - */ - getKeys(): Promise; - } - - /** Object representing the dialog box. */ - interface Dialog { - /** Method to close a dialog box. Returns a Promise. */ - close(): Promise; - } - - /** Provides display options and actions a dialog box may take. */ - interface DisplayWebDialogOptions { - /** - * Optional parameter that determines whether the dialog box displays as a popup (false) or within an IFrame (true). - * This setting is only applicable to custom functions running on Excel Online. - */ - displayInIFrame?: boolean; - /** - * Optional parameter that defines the height of the dialog box as a percentage of the current display. - * For example, accepts strings such as: '50%', '50'. - */ - height?: string; - /** - * Optional parameter that defines the width of dialog as a percentage of window. - * For example, accepts strings such as: '50%', '50'. - */ - width?: string; - /** - * Optional callback that runs when the dialog box sends a message to its parent. - */ - onMessage?: (message: string, dialog?: Dialog) => void; - /** - * Optional callback that runs when the dialog box is closed. - */ - onClose?: () => void; - /** - * Optional callback that runs when the dialog box sends an error. - */ - onRuntimeError?: (error: Error, dialog?: Dialog) => void; - } + getAccessToken(options?: AuthOptions): Promise; + } + /** + * Provides information about what Requirement Sets are supported in current environment. + */ + const apiInformation: ApiInformation; + /** + * Interface that contains functions for checking API requirement-set support. + */ + interface ApiInformation { + /** + * Check if the specified requirement set is supported by the host Office application. + * @param name - Set name; e.g., "MatrixBindings". + * @param minVersion - The minimum required version; e.g., "1.4". + */ + isSetSupported(name: string, minVersion?: string): boolean; + } } diff --git a/types/office-runtime/office-runtime-tests.ts b/types/office-runtime/office-runtime-tests.ts index 3bf93086c1..36a088a803 100644 --- a/types/office-runtime/office-runtime-tests.ts +++ b/types/office-runtime/office-runtime-tests.ts @@ -7,19 +7,27 @@ OfficeRuntime.storage.getItem("foo"); OfficeRuntime.storage.getItems(["foo", "bar"]); OfficeRuntime.storage.setItem("foo", "bar"); -OfficeRuntime.storage.setItems({ foo: "value1", bar: "value2"}); +OfficeRuntime.storage.setItems({ foo: "value1", bar: "value2" }); OfficeRuntime.storage.removeItem("foo"); OfficeRuntime.storage.removeItems(["foo", "bar"]); OfficeRuntime.storage.getKeys(); - OfficeRuntime.displayWebDialog("https://localhost:3000", { - displayInIFrame: false - }); +OfficeRuntime.displayWebDialog("https://localhost:3000", { + displayInIFrame: false +}); - OfficeRuntime.displayWebDialog("https://localhost:3000", { +OfficeRuntime.displayWebDialog("https://localhost:3000", { onClose: () => { console.log("closed"); } - }); +}); + +// Check for the support of the requirement-set (note that it only accepts strings.) +const supported = OfficeRuntime.apiInformation.isSetSupported("ExcelApi", "1.9"); + +// For SSO auth API, refer to the public documentation at the site: https://github.com/OfficeDev/Office-Add-in-NodeJS-SSO +OfficeRuntime.auth.getAccessToken({ allowSignInPrompt: true, forMSGraphAccess: true }).then(token => { + console.log(token); +});