diff --git a/CHANGELOG.md b/CHANGELOG.md index 72763f74b..009970fa2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,11 +15,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * Added a field to specify the Context type that intent can return to the AppD Application schema and extended the findIntent API calls to be able to use it for resolution. ([#499](https://github.com/finos/FDC3/pull/499)) * Added the ability to return a Channel from an intent (via the `IntentResult` type), resolver support for intents that return Channels and the concept of PrivateChannels. ([#508](https://github.com/finos/FDC3/pull/508)) * 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)) diff --git a/docs/api/ref/Errors.md b/docs/api/ref/Errors.md index eb05d98bf..ad30be91a 100644 --- a/docs/api/ref/Errors.md +++ b/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 ResultError { + /** Returned if the intent handler exited without returning a Promise or that Promise was not resolved with a Context or Channel object. */ NoResultReturned = 'NoResultReturned', + /** 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', } ``` diff --git a/src/api/AppIntent.ts b/src/api/AppIntent.ts index 1d294663c..57475ddcb 100644 --- a/src/api/AppIntent.ts +++ b/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'; diff --git a/src/api/AppMetadata.ts b/src/api/AppMetadata.ts index dd9a2ec7b..33c0c3591 100644 --- a/src/api/AppMetadata.ts +++ b/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'; diff --git a/src/api/Channel.ts b/src/api/Channel.ts index b37d51971..bda96fe31 100644 --- a/src/api/Channel.ts +++ b/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'; diff --git a/src/api/DisplayMetadata.ts b/src/api/DisplayMetadata.ts index 1c89ae8cc..e775a6145 100644 --- a/src/api/DisplayMetadata.ts +++ b/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 */ /** diff --git a/src/api/Errors.ts b/src/api/Errors.ts index 3a755e14a..c49881889 100644 --- a/src/api/Errors.ts +++ b/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 ResultError { + /** Returned if the intent handler exited without returning a Promise or that Promise was not resolved with a Context or Channel object. */ NoResultReturned = 'NoResultReturned', + /** 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', } diff --git a/src/api/Icon.ts b/src/api/Icon.ts index 2d28fdf73..b19cfe7bb 100644 --- a/src/api/Icon.ts +++ b/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 { diff --git a/src/api/ImplementationMetadata.ts b/src/api/ImplementationMetadata.ts index 3def6ecb3..ba68d867a 100644 --- a/src/api/ImplementationMetadata.ts +++ b/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 */ /** diff --git a/src/api/IntentMetadata.ts b/src/api/IntentMetadata.ts index edc585add..41e7280ee 100644 --- a/src/api/IntentMetadata.ts +++ b/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 */ /** diff --git a/src/api/IntentResolution.ts b/src/api/IntentResolution.ts index 1f3865744..9571f1af8 100644 --- a/src/api/IntentResolution.ts +++ b/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 { IntentResult } from './Types'; diff --git a/src/api/Listener.ts b/src/api/Listener.ts index 91f3de0b3..ced9e2e31 100644 --- a/src/api/Listener.ts +++ b/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 { diff --git a/src/api/Types.ts b/src/api/Types.ts index b924529a7..c1ee70d16 100644 --- a/src/api/Types.ts +++ b/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, Channel } from '..';