581 add intent delivery failed error and document errors

CHANGELOG.md

@@ -13,11 +13,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Added advice on how to `broadcast` complex context types, composed of other types, so that other apps can listen for both the complex type and simpler constituent types ([#464](https://github.com/finos/FDC3/pull/464))
 * Added the ability to return data from an intent, via the addition of an IntentHandler type and a `getResult()` to IntentResolution, both of which return a Promise of a Context object. ([#495](https://github.com/finos/FDC3/pull/495))
 * Added error `UserCancelled` to the `ResolveError` enumeration to be used when user closes the resolver UI or otherwise cancels resolution of a raised intent ([#522 ](https://github.com/finos/FDC3/pull/522))
-* Added an `instanceId` (and optional `instanceMetadata`) field to `AppMetadata` allowing it to refer to specific app instances and thereby supporting targetting of intents to specific app instances. Also added a `findInstanes()` function to the desktop agent. ([#509]((https://github.com/finos/FDC3/pull/509))
+* Added an `instanceId` (and optional `instanceMetadata`) field to `AppMetadata` allowing it to refer to specific app instances and thereby supporting targetting of intents to specific app instances. Also added a `findInstances()` function to the desktop agent and `TargetAppUnavailable` and `TargetInstanceUnavailable` Errors to the `ResolveError` enumeration. ([#509]((https://github.com/finos/FDC3/pull/509))
 * Added a References and Bibliography section to the Standard's documentation to hold links to 'normative references' and other documentation that is useful for understanding the standard ([#530](https://github.com/finos/FDC3/pull/530))
 * `IntentResolution` now requires the name of the intent raised to included, allowing it to be used to determine the intent raised via `fdc3.raiseIntentForContext()`. ([#507](https://github.com/finos/FDC3/pull/507))
 * A Trademarks page was added to acknowledge trademarks used within the Standard not owned by FINOS or the Linux Foundation ([#534](https://github.com/finos/FDC3/pull/534))
 * Added details of FDC3's existing versioning and deprecation policies to the FDC3 compliance page ([#539](https://github.com/finos/FDC3/pull/539))
+* Add `IntentDeliveryFailed` to the `ResolveError` enumeration to be used when delivery of an intent and context to a targetted app or instance fails. ([#601](https://github.com/finos/FDC3/pull/601))
 
 ### Changed
 * Consolidated `Listener` documentation with other types ([#404](https://github.com/finos/FDC3/pull/404))

docs/api/ref/Errors.md

@@ -8,10 +8,14 @@ Some FDC3 API operations return promises that can result in errors.
 
 ```typescript
 enum OpenError {
-  AppNotFound = "AppNotFound",
-  ErrorOnLaunch = "ErrorOnLaunch",
-  AppTimeout = "AppTimeout",
-  ResolverUnavailable = "ResolverUnavailable"
+  /** Returned if the specified application is not found.*/
+  AppNotFound = 'AppNotFound',
+  /** Returned if the specified application fails to launch correctly.*/
+  ErrorOnLaunch = 'ErrorOnLaunch',
+  /** Returned if the specified application launches but fails to add a context listener in order to receive the context passed to the `fdc3.open` call.*/
+  AppTimeout = 'AppTimeout',
+  /** Returned if the FDC3 desktop agent implementation is not currently able to handle the request.*/
+  ResolverUnavailable = 'ResolverUnavailable',
 }
 ```
 
@@ -24,12 +28,20 @@ Contains constants representing the errors that can be encountered when calling
 
 ```typescript
 export enum ResolveError {
+  /** SHOULD be returned if no apps are available that can resolve the intent and context combination.*/
   NoAppsFound = 'NoAppsFound',
+  /** Returned if the FDC3 desktop agent implementation is not currently able to handle the request.*/
   ResolverUnavailable = 'ResolverUnavailable',
+  /** Returned if the user cancelled the resolution request, for example by closing or cancelling a resolver UI.*/
   UserCancelled = 'UserCancelledResolution',
+  /** SHOULD be returned if a timeout cancels an intent resolution that required user interaction. Please use `ResolverUnavailable` instead for situations where a resolver UI or similar fails.*/
   ResolverTimeout = 'ResolverTimeout',
+  /** Returned if a specified target application is not available or a new instance of it cannot be opened. */
   TargetAppUnavailable = 'TargetAppUnavailable',
-  TargetInstanceUnavailable = 'TargetInstanceUnavailable'
+  /** Returned if a specified target application instance is not available, for example because it has been closed. */
+  TargetInstanceUnavailable = 'TargetInstanceUnavailable',
+  /** Returned if the intent and context could not be delivered to the selected application or instance, for example because it has not added an intent handler within a timeout.*/
+  IntentDeliveryFailed = 'IntentDeliveryFailed',
 }
 ```
 
@@ -45,7 +57,9 @@ Contains constants representing the errors that can be encountered when calling
 
 ```typescript
 enum DataError {
+  /** Returned if the intent handler exited without returning a Promise or that Promise was not resolved with a Context object. */
   NoDataReturned = 'NoDataReturned',
+  /** Returned if the Intent handler function processing the raised intent throws an error or rejects the Promise it returned. */
   IntentHandlerRejected = 'IntentHandlerRejected',
 }
 ```
@@ -61,9 +75,12 @@ Contains constants representing the errors that can be encountered when calling
 
 ```typescript
 enum ChannelError {
-  NoChannelFound = "NoChannelFound",
-  AccessDenied = "AccessDenied",
-  CreationFailed = "CreationFailed"
+  /** Returned if the specified channel is not found when attempting to join a channel via the `joinUserChannel` function of the DesktopAgent (`fdc3`).*/
+  NoChannelFound = 'NoChannelFound',
+  /** SHOULD be returned when a request to join a user channel or to a retrieve a Channel object via the `joinUserChannel` or `getOrCreateChannel` methods of the DesktopAgent (`fdc3`) object is denied. */
+  AccessDenied = 'AccessDenied',
+  /** SHOULD be returned when a channel cannot be created or retrieved via the `getOrCreateChannel` method of the DesktopAgent (`fdc3`).*/
+  CreationFailed = 'CreationFailed',
 }
 ```
 

src/api/AppIntent.ts

@@ -1,6 +1,6 @@
 /**
  * SPDX-License-Identifier: Apache-2.0
- * Copyright 2019 FINOS FDC3 contributors - see NOTICE file
+ * Copyright FINOS FDC3 contributors - see NOTICE file
  */
 
 import { AppMetadata } from './AppMetadata';

src/api/AppMetadata.ts

@@ -1,6 +1,6 @@
 /**
  * SPDX-License-Identifier: Apache-2.0
- * Copyright 2019 FINOS FDC3 contributors - see NOTICE file
+ * Copyright FINOS FDC3 contributors - see NOTICE file
  */
 
 import { Icon } from './Icon';

src/api/Channel.ts

@@ -1,6 +1,6 @@
 /**
  * SPDX-License-Identifier: Apache-2.0
- * Copyright 2019 FINOS FDC3 contributors - see NOTICE file
+ * Copyright FINOS FDC3 contributors - see NOTICE file
  */
 
 import { Context } from '../context/ContextTypes';

src/api/DesktopAgent.ts

@@ -1,6 +1,6 @@
 /**
  * SPDX-License-Identifier: Apache-2.0
- * Copyright 2019 FINOS FDC3 contributors - see NOTICE file
+ * Copyright FINOS FDC3 contributors - see NOTICE file
  */
 
 import { AppIntent } from './AppIntent';

src/api/DisplayMetadata.ts

@@ -1,6 +1,6 @@
 /**
  * SPDX-License-Identifier: Apache-2.0
- * Copyright 2019 FINOS FDC3 contributors - see NOTICE file
+ * Copyright FINOS FDC3 contributors - see NOTICE file
  */
 
 /**

src/api/Errors.ts

@@ -1,31 +1,50 @@
 /**
  * SPDX-License-Identifier: Apache-2.0
- * Copyright 2019 FINOS FDC3 contributors - see NOTICE file
+ * Copyright FINOS FDC3 contributors - see NOTICE file
  */
 
+/** Constants representing the errors that can be encountered when calling the `open` method on the DesktopAgent object (`fdc3`). */
 export enum OpenError {
+  /** Returned if the specified application is not found.*/
   AppNotFound = 'AppNotFound',
+  /** Returned if the specified application fails to launch correctly.*/
   ErrorOnLaunch = 'ErrorOnLaunch',
+  /** Returned if the specified application launches but fails to add a context listener in order to receive the context passed to the `fdc3.open` call.*/
   AppTimeout = 'AppTimeout',
+  /** Returned if the FDC3 desktop agent implementation is not currently able to handle the request.*/
   ResolverUnavailable = 'ResolverUnavailable',
 }
 
+/** Constants representing the errors that can be encountered when calling the `findIntent`, `findIntentsByContext`, `raiseIntent` or `raiseIntentForContext` methods on the DesktopAgent (`fdc3`). */
 export enum ResolveError {
+  /** SHOULD be returned if no apps are available that can resolve the intent and context combination.*/
   NoAppsFound = 'NoAppsFound',
+  /** Returned if the FDC3 desktop agent implementation is not currently able to handle the request.*/
   ResolverUnavailable = 'ResolverUnavailable',
+  /** Returned if the user cancelled the resolution request, for example by closing or cancelling a resolver UI.*/
   UserCancelled = 'UserCancelledResolution',
+  /** SHOULD be returned if a timeout cancels an intent resolution that required user interaction. Please use `ResolverUnavailable` instead for situations where a resolver UI or similar fails.*/
   ResolverTimeout = 'ResolverTimeout',
+  /** Returned if a specified target application is not available or a new instance of it cannot be opened. */
   TargetAppUnavailable = 'TargetAppUnavailable',
+  /** Returned if a specified target application instance is not available, for example because it has been closed. */
   TargetInstanceUnavailable = 'TargetInstanceUnavailable',
+  /** Returned if the intent and context could not be delivered to the selected application or instance, for example because it has not added an intent handler within a timeout.*/
+  IntentDeliveryFailed = 'IntentDeliveryFailed',
 }
 
 export enum DataError {
+  /** Returned if the intent handler exited without returning a Promise or that Promise was not resolved with a Context object. */
   NoDataReturned = 'NoDataReturned',
+  /** Returned if the Intent handler function processing the raised intent throws an error or rejects the Promise it returned. */
   IntentHandlerRejected = 'IntentHandlerRejected',
 }
 
 export enum ChannelError {
+  /** Returned if the specified channel is not found when attempting to join a channel via the `joinUserChannel` function  of the DesktopAgent (`fdc3`).*/
   NoChannelFound = 'NoChannelFound',
+  /** SHOULD be returned when a request to join a user channel or to a retrieve a Channel object via the `joinUserChannel` or `getOrCreateChannel` methods of the DesktopAgent (`fdc3`) object is denied. */
   AccessDenied = 'AccessDenied',
+  /** SHOULD be returned when a channel cannot be created or retrieved via the `getOrCreateChannel` method of the DesktopAgent (`fdc3`).*/
   CreationFailed = 'CreationFailed',
 }

src/api/Icon.ts

@@ -1,6 +1,6 @@
 /**
  * SPDX-License-Identifier: Apache-2.0
- * Copyright 2019 FINOS FDC3 contributors - see NOTICE file
+ * Copyright FINOS FDC3 contributors - see NOTICE file
  */
 
 export interface Icon {

src/api/ImplementationMetadata.ts

@@ -1,6 +1,6 @@
 /**
  * SPDX-License-Identifier: Apache-2.0
- * Copyright 2021 FINOS FDC3 contributors - see NOTICE file
+ * Copyright FINOS FDC3 contributors - see NOTICE file
  */
 
 /**

src/api/IntentMetadata.ts

@@ -1,6 +1,6 @@
 /**
  * SPDX-License-Identifier: Apache-2.0
- * Copyright 2019 FINOS FDC3 contributors - see NOTICE file
+ * Copyright FINOS FDC3 contributors - see NOTICE file
  */
 
 /**

src/api/IntentResolution.ts

@@ -1,6 +1,6 @@
 /**
  * SPDX-License-Identifier: Apache-2.0
- * Copyright 2019 FINOS FDC3 contributors - see NOTICE file
+ * Copyright FINOS FDC3 contributors - see NOTICE file
  */
 
 import { Context } from '../context/ContextTypes';

src/api/Listener.ts

@@ -1,6 +1,6 @@
 /**
  * SPDX-License-Identifier: Apache-2.0
- * Copyright 2019 FINOS FDC3 contributors - see NOTICE file
+ * Copyright FINOS FDC3 contributors - see NOTICE file
  */
 
 export interface Listener {

src/api/Types.ts

@@ -1,6 +1,6 @@
 /**
  * SPDX-License-Identifier: Apache-2.0
- * Copyright 2019 FINOS FDC3 contributors - see NOTICE file
+ * Copyright FINOS FDC3 contributors - see NOTICE file
  */
 
 import { AppMetadata } from '..';