@types/office-js-preview 1.0.361 → 1.0.363

office-js-preview/README.md

@@ -8,7 +8,7 @@ This package contains type definitions for Office.js (https://github.com/OfficeD
 Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/office-js-preview.
 
 ### Additional Details
- * Last updated: Wed, 07 Dec 2022 18:03:36 GMT
+ * Last updated: Thu, 15 Dec 2022 19:33:14 GMT
  * Dependencies: none
  * Global values: `Excel`, `Office`, `OfficeCore`, `OfficeExtension`, `OneNote`, `PowerPoint`, `Visio`, `Word`
 

office-js-preview/index.d.ts

@@ -653,14 +653,12 @@ declare namespace Office {
         onVisibilityModeChanged(
             handler: (message: VisibilityModeChangedMessage) => void,
         ): Promise<() => Promise<void>>;
-
         /**
          * Represents a modal notification dialog that can appear when the user attempts to close a document. The document won't close until the user responds.
          * This API is only supported in Excel.
          *
          * @remarks
-         * [Api set: SharedRuntime BETA (PREVIEW ONLY)]
-         * @beta
+         * **Requirement set**: {@link https://learn.microsoft.com/javascript/api/requirement-sets/common/shared-runtime-requirement-sets | SharedRuntime 1.2}
         */
         beforeDocumentCloseNotification: BeforeDocumentCloseNotification;
     }
@@ -670,8 +668,7 @@ declare namespace Office {
      * This API is only supported in Excel.
      *
      * @remarks
-     * [Api set: SharedRuntime BETA (PREVIEW ONLY)]
-     * @beta
+     * **Requirement set**: {@link https://learn.microsoft.com/javascript/api/requirement-sets/common/shared-runtime-requirement-sets | SharedRuntime 1.2}
      */
     interface BeforeDocumentCloseNotification {
         /**
@@ -680,8 +677,7 @@ declare namespace Office {
          * The `BeforeDocumentCloseNotification` API is only supported in Excel.
          *
          * @remarks
-         * [Api set: SharedRuntime BETA (PREVIEW ONLY)]
-         * @beta
+         * **Requirement set**: {@link https://learn.microsoft.com/javascript/api/requirement-sets/common/shared-runtime-requirement-sets | SharedRuntime 1.2}
          */
         enable(): Promise<void>;
 
@@ -690,26 +686,24 @@ declare namespace Office {
          * The `BeforeDocumentCloseNotification` API is only supported in Excel.
          *
          * @remarks
-         * [Api set: SharedRuntime BETA (PREVIEW ONLY)]
-         * @beta
+         * **Requirement set**: {@link https://learn.microsoft.com/javascript/api/requirement-sets/common/shared-runtime-requirement-sets | SharedRuntime 1.2}
          */
         disable(): Promise<void>;
 
         /**
          * Adds an event handler that detects when the `BeforeDocumentCloseNotification` close operation is cancelled. 
-         * This event handler will be triggered if one of the following conditions is met.
-         *
-         * 1. When the notification dialog is open, the end user clicks the **Don't close** button within the dialog, clicks the Close button in the upper right corner of the dialog, or presses the Esc key.
+         * This event handler will be triggered if both of the following conditions are met.
          *
-         * 2. When the add-in calls the `enable` method on the `BeforeDocumentCloseNotification` object.
+         * 1. The add-in calls the `enable` method on the `BeforeDocumentCloseNotification` object.
+         * 
+         * 2. When the notification dialog is open, the end user clicks the **Don't close** button within the dialog, clicks the Close button in the upper right corner of the dialog, or presses the Esc key.
          *
          * The `BeforeDocumentCloseNotification` API is only supported in Excel.
          * @param handler The event handler that is called when the dialog is cancelled.
          * @returns A promise that resolves when the event handler is added.
          *
          * @remarks
-         * [Api set: SharedRuntime BETA (PREVIEW ONLY)]
-         * @beta
+         * **Requirement set**: {@link https://learn.microsoft.com/javascript/api/requirement-sets/common/shared-runtime-requirement-sets | SharedRuntime 1.2}
         */
         onCloseActionCancelled(
             handler: () => void
@@ -10595,16 +10589,19 @@ declare namespace Office {
         /**
          * Asynchronously loads custom properties for this add-in on the selected item.
          *
-         * Custom properties are stored as key/value pairs on a per-app, per-item basis.
-         * This method returns a `CustomProperties` object in the callback, which provides methods to access the custom properties specific to the
-         * current item and the current add-in. Custom properties are not encrypted on the item, so this should not be used as secure storage.
+         * Custom properties are stored as key-value pairs on a per-app, per-item basis.
+         * This method returns a {@link Office.CustomProperties | CustomProperties} object in the callback, which provides methods to access the custom properties specific to the
+         * current item and the current add-in. Custom properties aren't encrypted on the item, so this shouldn't be used as secure storage.
          *
          * The custom properties are provided as a `CustomProperties` object in the `asyncResult.value` property.
-         * This object can be used to get, set, and remove custom properties from the item and save changes to the custom property set back to
-         * the server.
+         * This object can be used to get, set, save, and remove custom properties from the mail item.
          *
          * @remarks
+         * [Api set: Mailbox 1.1]
          *
+         * To learn more about custom properties, see
+         * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/metadata-for-an-outlook-add-in | Get and set add-in metadata for an Outlook add-in}.
+         * 
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: `ReadItem`
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Appointment Organizer
@@ -11896,16 +11893,19 @@ declare namespace Office {
         /**
          * Asynchronously loads custom properties for this add-in on the selected item.
          *
-         * Custom properties are stored as key/value pairs on a per-app, per-item basis.
-         * This method returns a `CustomProperties` object in the callback, which provides methods to access the custom properties specific to the
-         * current item and the current add-in. Custom properties are not encrypted on the item, so this should not be used as secure storage.
+         * Custom properties are stored as key-value pairs on a per-app, per-item basis.
+         * This method returns a {@link Office.CustomProperties | CustomProperties} object in the callback, which provides methods to access the custom properties specific to the
+         * current item and the current add-in. Custom properties aren't encrypted on the item, so this shouldn't be used as secure storage.
          *
-         * The custom properties are provided as a `CustomProperties` object in the asyncResult.value property.
-         * This object can be used to get, set, and remove custom properties from the item and save changes to the custom property set back to
-         * the server.
+         * The custom properties are provided as a `CustomProperties` object in the `asyncResult.value` property.
+         * This object can be used to get, set, save, and remove custom properties from the mail item.
          *
          * @remarks
+         * [Api set: Mailbox 1.1]
          *
+         * To learn more about custom properties, see
+         * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/metadata-for-an-outlook-add-in | Get and set add-in metadata for an Outlook add-in}.
+         * 
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: `ReadItem`
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Appointment Attendee
@@ -12768,15 +12768,27 @@ declare namespace Office {
         urls: string[];
     }
     /**
-     * The `CustomProperties` object represents custom properties that are specific to a particular item and specific to a mail add-in for Outlook.
-     * For example, there might be a need for a mail add-in to save some data that is specific to the current email message that activated the add-in.
-     * If the user revisits the same message in the future and activates the mail add-in again, the add-in will be able to retrieve the data that had
-     * been saved as custom properties. **Important**: The maximum length of a `CustomProperties` JSON object is 2500 characters.
+     * The `CustomProperties` object represents custom properties that are specific to a particular mail item and specific to an Outlook add-in.
+     * For example, there might be a need for an add-in to save some data that's specific to the current message that activated the add-in.
+     * If the user revisits the same message in the future and activates the add-in again, the add-in will be able to retrieve the data that had
+     * been saved as custom properties. 
      *
-     * Because Outlook on Mac doesn't cache custom properties, if the user's network goes down, mail add-ins cannot access their custom properties.
+     * To learn more about `CustomProperties`, see
+     * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/metadata-for-an-outlook-add-in | Get and set add-in metadata for an Outlook add-in}.
      *
      * @remarks
+     * [Api set: Mailbox 1.1]
+     * 
+     * When using custom properties in your add-in, keep in mind that:
+     * 
+     * - Custom properties saved while in compose mode aren't transmitted to recipients of the mail item. When a message or appointment with custom
+     * properties is sent, its properties can be accessed from the item in the Sent Items folder.
+     * If you want to make custom data accessible to recipients, consider using {@link Office.InternetHeaders | InternetHeaders} instead.
+     * 
+     * - The maximum length of a `CustomProperties` JSON object is 2500 characters.
      *
+     * - Outlook on Mac doesn't cache custom properties. If the user's network goes down, mail add-ins can't access their custom properties.
+     * 
      * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: `ReadItem`
      *
      * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Compose or Read
@@ -12788,6 +12800,7 @@ declare namespace Office {
          * @returns The value of the specified custom property.
          *
          * @remarks
+         * [Api set: Mailbox 1.1]
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: `ReadItem`
          *
@@ -12821,6 +12834,7 @@ declare namespace Office {
          * To make the removal of the property permanent, you must call the `saveAsync` method of the `CustomProperties` object.
          *
          * @remarks
+         * [Api set: Mailbox 1.1]
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: `ReadItem`
          *
@@ -12830,7 +12844,7 @@ declare namespace Office {
          */
         remove(name: string): void;
         /**
-         * Saves item-specific custom properties to the server.
+         * Saves custom properties to a message or appointment.
          *
          * You must call the `saveAsync` method to persist any changes made with the `set` method or the `remove` method of the `CustomProperties` object.
          * The saving action is asynchronous.
@@ -12842,7 +12856,11 @@ declare namespace Office {
          * Your callback function should handle this error accordingly.
          *
          * @remarks
-         *
+         * [Api set: Mailbox 1.1]
+         * 
+         * **Important**: In Outlook on Windows, custom properties saved while in compose mode only persist after the item being composed is closed or
+         * after `Office.context.mailbox.item.saveAsync` is called.
+         * 
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: `ReadItem`
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Compose or Read
@@ -12853,7 +12871,7 @@ declare namespace Office {
          */
         saveAsync(callback: (asyncResult: Office.AsyncResult<void>) => void, asyncContext?: any): void;
         /**
-         * Saves item-specific custom properties to the server.
+         * Saves custom properties to a message or appointment.
          *
          * You must call the `saveAsync` method to persist any changes made with the `set` method or the `remove` method of the `CustomProperties` object.
          * The saving action is asynchronous.
@@ -12865,7 +12883,8 @@ declare namespace Office {
          * Your callback function should handle this error accordingly.
          *
          * @remarks
-         *
+         * [Api set: Mailbox 1.1]
+         * 
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: `ReadItem`
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Compose or Read
@@ -12876,14 +12895,16 @@ declare namespace Office {
         /**
          * Sets the specified property to the specified value.
          *
-         * The `set` method sets the specified property to the specified value. You must use the `saveAsync` method to save the property to the server.
+         * The `set` method sets the specified property to the specified value. To ensure that the set property and value persist on the mail item,
+         * you must call the `saveAsync` method.
          *
          * The `set` method creates a new property if the specified property does not already exist;
          * otherwise, the existing value is replaced with the new value.
          * The `value` parameter can be of any type; however, it is always passed to the server as a string.
          *
          * @remarks
-         *
+         * [Api set: Mailbox 1.1]
+         * 
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: `ReadItem`
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Compose or Read
@@ -15865,16 +15886,19 @@ declare namespace Office {
         /**
          * Asynchronously loads custom properties for this add-in on the selected item.
          *
-         * Custom properties are stored as key/value pairs on a per-app, per-item basis.
-         * This method returns a `CustomProperties` object in the callback, which provides methods to access the custom properties specific to the
-         * current item and the current add-in. Custom properties are not encrypted on the item, so this should not be used as secure storage.
+         * Custom properties are stored as key-value pairs on a per-app, per-item basis.
+         * This method returns a {@link Office.CustomProperties | CustomProperties} object in the callback, which provides methods to access the custom properties specific to the
+         * current item and the current add-in. Custom properties aren't encrypted on the item, so this shouldn't be used as secure storage.
          *
          * The custom properties are provided as a `CustomProperties` object in the `asyncResult.value` property.
-         * This object can be used to get, set, and remove custom properties from the item and save changes to the custom property set back to
-         * the server.
+         * This object can be used to get, set, save, and remove custom properties from the mail item.
          *
          * @remarks
+         * [Api set: Mailbox 1.1]
          *
+         * To learn more about custom properties, see
+         * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/metadata-for-an-outlook-add-in | Get and set add-in metadata for an Outlook add-in}.
+         * 
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: `ReadItem`
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Message Compose
@@ -17052,15 +17076,19 @@ declare namespace Office {
         /**
          * Asynchronously loads custom properties for this add-in on the selected item.
          *
-         * Custom properties are stored as key/value pairs on a per-app, per-item basis.
-         * This method returns a `CustomProperties` object in the callback, which provides methods to access the custom properties specific to the
-         * current item and the current add-in. Custom properties are not encrypted on the item, so this should not be used as secure storage.
+         * Custom properties are stored as key-value pairs on a per-app, per-item basis.
+         * This method returns a {@link Office.CustomProperties | CustomProperties} object in the callback, which provides methods to access the custom properties specific to the
+         * current item and the current add-in. Custom properties aren't encrypted on the item, so this shouldn't be used as secure storage.
          *
          * The custom properties are provided as a `CustomProperties` object in the `asyncResult.value` property.
-         * This object can be used to get, set, and remove custom properties from the item and save changes to the custom property set back to the server.
+         * This object can be used to get, set, save, and remove custom properties from the mail item.
          *
          * @remarks
+         * [Api set: Mailbox 1.1]
          *
+         * To learn more about custom properties, see
+         * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/metadata-for-an-outlook-add-in | Get and set add-in metadata for an Outlook add-in}.
+         * 
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: `ReadItem`
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Message Read
@@ -18207,26 +18235,30 @@ declare namespace Office {
      * The settings created by using the methods of the `RoamingSettings` object are saved per add-in and per user.
      * That is, they are available only to the add-in that created them, and only from the user's mailbox in which they are saved.
      *
-     * While the Outlook add-in API limits access to these settings to only the add-in that created them, these settings should not be considered
+     * While the Outlook add-in API limits access to these settings to only the add-in that created them, these settings shouldn't be considered
      * secure storage. They can be accessed by Exchange Web Services or Extended MAPI.
-     * They should not be used to store sensitive information such as user credentials or security tokens.
+     * They shouldn't be used to store sensitive information, such as user credentials or security tokens.
      *
      * The name of a setting is a String, while the value can be a String, Number, Boolean, null, Object, or Array.
      *
      * The `RoamingSettings` object is accessible via the `roamingSettings` property in the `Office.context` namespace.
+     * 
+     * To learn more about `RoamingSettings`, see
+     * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/metadata-for-an-outlook-add-in | Get and set add-in metadata for an Outlook add-in}.
+     *
+     * @remarks
+     * [Api set: Mailbox 1.1]
      *
      * **Important**:
      *
      * - The `RoamingSettings` object is initialized from the persisted storage only when the add-in is first loaded.
-     * For task panes, this means that it is only initialized when the task pane first opens.
+     * For task panes, this means that it's only initialized when the task pane first opens.
      * If the task pane navigates to another page or reloads the current page, the in-memory object is reset to its initial values, even if
      * your add-in has persisted changes.
      * The persisted changes will not be available until the task pane (or item in the case of UI-less add-ins) is closed and reopened.
      *
      * - When set and saved through Outlook on Windows or Mac, these settings are reflected in Outlook on the web only after a browser refresh.
      *
-     * @remarks
-     *
      * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: `Restricted`
      *
      * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Compose or Read
@@ -18238,6 +18270,7 @@ declare namespace Office {
          * @returns Type: String | Number | Boolean | Object | Array
          *
          * @remarks
+         * [Api set: Mailbox 1.1]
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: `Restricted`
          *
@@ -18247,9 +18280,10 @@ declare namespace Office {
          */
         get(name: string): any;
         /**
-         * Removes the specified setting
+         * Removes the specified setting.
          *
          * @remarks
+         * [Api set: Mailbox 1.1]
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: `Restricted`
          *
@@ -18261,11 +18295,12 @@ declare namespace Office {
         /**
          * Saves the settings.
          *
-         * Any settings previously saved by an add-in are loaded when it is initialized, so during the lifetime of the session you can just use
+         * Any settings previously saved by an add-in are loaded when it's initialized, so during the lifetime of the session you can just use
          * the set and get methods to work with the in-memory copy of the settings property bag.
-         * When you want to persist the settings so that they are available the next time the add-in is used, use the saveAsync method.
+         * When you want to persist the settings so that they're available the next time the add-in is used, use the `saveAsync` method.
          *
          * @remarks
+         * [Api set: Mailbox 1.1]
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: `Restricted`
          *
@@ -18278,7 +18313,7 @@ declare namespace Office {
         /**
          * Sets or creates the specified setting.
          *
-         * The `set` method creates a new setting of the specified name if it does not already exist, or sets an existing setting of the specified name.
+         * The `set` method creates a new setting of the specified name if it doesn't already exist, or sets an existing setting of the specified name.
          * The value is stored in the document as the serialized JSON representation of its data type.
          *
          * A maximum of 32KB is available for the settings of each add-in.
@@ -18286,6 +18321,7 @@ declare namespace Office {
          * Any changes made to settings using the `set` method will not be saved to the server until the `saveAsync` method is called.
          *
          * @remarks
+         * [Api set: Mailbox 1.1]
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: `Restricted`
          *

office-js-preview/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@types/office-js-preview",
-    "version": "1.0.361",
+    "version": "1.0.363",
     "description": "TypeScript definitions for Office.js",
     "homepage": "https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/office-js-preview",
     "license": "MIT",
@@ -45,6 +45,6 @@
     },
     "scripts": {},
     "dependencies": {},
-    "typesPublisherContentHash": "f2beca111504af9b2f903cc76d4f74740ca229d76b4cd7cc46510aa07ddba7a4",
+    "typesPublisherContentHash": "49b4e9b8c2bc09c8b8d8ffb74f2236f69d654aeb759c708c1a14e7e25f8cc7e0",
     "typeScriptVersion": "4.2"
 }