mirror of
https://github.com/gosticks/DefinitelyTyped.git
synced 2025-10-16 12:05:41 +00:00
Addition of new auth API (preview) and ApiInformation interface. (#40018)
* Office Runtime Auth Public Preview APIs * Add isSetSupported from ApiInformation interface * Example addition * Fixes to API description * Fix trailing space and blank lines * Fixes to comment alignment * adding example in test file for SSO * adding example in test file for SSO with semi-colon
This commit is contained in:
Sudhi Ramamurthy
Nathan Shively-Sanders
parent
072a21ae95
commit
8043169d09
265
types/office-runtime/index.d.ts
vendored
265
types/office-runtime/index.d.ts
vendored
@ -3,111 +3,194 @@
|
||||
// Definitions by: Michael Zlatskovsky <https://github.com/Zlatkovsky>, Michelle Scharlock <https://github.com/mscharlock>
|
||||
// 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<Dialog>;
|
||||
/**
|
||||
* 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<Dialog>;
|
||||
getItem(key: string): Promise<string | null>;
|
||||
/**
|
||||
* 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<void>;
|
||||
/**
|
||||
* 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<void>;
|
||||
/**
|
||||
* 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<void>;
|
||||
/**
|
||||
* 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<void>;
|
||||
/**
|
||||
* Retrieves an array of all keys from storage.
|
||||
* Returns a Promise.
|
||||
*/
|
||||
getKeys(): Promise<string[]>;
|
||||
}
|
||||
/** Object representing the dialog box. */
|
||||
interface Dialog {
|
||||
/** Method to close a dialog box. Returns a Promise. */
|
||||
close(): Promise<void>;
|
||||
}
|
||||
/** 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<string | null>;
|
||||
/**
|
||||
* 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<void>;
|
||||
/**
|
||||
* 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<void>;
|
||||
/**
|
||||
* 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<void>;
|
||||
/**
|
||||
* 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<void>;
|
||||
/**
|
||||
* Retrieves an array of all keys from storage.
|
||||
* Returns a Promise.
|
||||
*/
|
||||
getKeys(): Promise<string[]>;
|
||||
}
|
||||
|
||||
/** Object representing the dialog box. */
|
||||
interface Dialog {
|
||||
/** Method to close a dialog box. Returns a Promise. */
|
||||
close(): Promise<void>;
|
||||
}
|
||||
|
||||
/** 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<string>;
|
||||
}
|
||||
/**
|
||||
* 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;
|
||||
}
|
||||
}
|
||||
|
||||
@ -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);
|
||||
});
|
||||
|
||||
Loading…
Reference in New Issue
Block a user