Merge branch 'finos:master' into 592-intent-proposal-create-interaction

CHANGELOG.md

@@ -100,6 +100,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Clarified the description of the addContextListener functions from the Desktop Agent and Channel APIs in spec and docs. ([#492](https://github.com/finos/FDC3/pull/492))
 * Clarified that implementing `fdc3.getInfo()` is required for compliance with the FDC3 standard ([#515](https://github.com/finos/FDC3/pull/515))
 * Corrected syntax errors in valuation schema ([#834](https://github.com/finos/FDC3/pull/834))
+* Clarified that API errors are promises rejected with a JavaScript (or language appropriate) Error Object with a message chosen from the error enumerations. ([#843](https://github.com/finos/FDC3/pull/843))
+* Clarified that `findIntent` functions should return the `ResolveError.NoAppsFound` error, rather than an `AppIntent` with an empty `apps` array when no apps are fund during intent resolution. ([#843](https://github.com/finos/FDC3/pull/843))
+* Clarified spec requirements for registration of intent handlers (SHOULD support `interop.intents.listensFor` in an appD record, may support other routes including dynamic registration at runtime) ([#844](https://github.com/finos/FDC3/pull/844))
+* Corrected schema definition for appD `interop.intents.listensFor` element ([#847](https://github.com/finos/FDC3/pull/847))
 
 ## [npm v1.2.0] - 2021-04-19
 

docs/api/ref/Channel.md

@@ -132,7 +132,7 @@ public broadcast(context: Context): Promise<void>;
 
 Broadcasts a context on the channel. This function can be used without first joining the channel, allowing applications to broadcast on both App Channels and User Channels that they aren't a member of.
 
-If the broadcast is denied by the channel or the channel is not available, the method will return an `Error` with a string from the [`ChannelError`](ChannelError) enumeration.
+If the broadcast is denied by the channel or the channel is not available, the promise will be rejected with an `Error` with a `message` string from the [`ChannelError`](ChannelError) enumeration.
 
 Channel implementations should ensure that context messages broadcast by an application on a channel should not be delivered back to that same application if they are joined to the channel.
 
@@ -173,7 +173,7 @@ If no _context type_ is provided, the most recent context that was broadcast on
 
 It is up to the specific Desktop Agent implementation whether and how recent contexts are stored. For example, an implementation could store context history for a channel in a single array and search through the array for the last context matching a provided type, or context could be maintained as a dictionary keyed by context types. An implementation could also choose not to support context history, in which case this method will return `null` for any context type not matching the type of the most recent context.
 
-If getting the current context fails, the promise will return an `Error` with a string from the [`ChannelError`](ChannelError) enumeration.
+If getting the current context fails, the promise will be rejected with an `Error` with a `message` string from the [`ChannelError`](ChannelError) enumeration.
 
 #### Examples
 

docs/api/ref/DesktopAgent.md

@@ -150,6 +150,7 @@ fdc3.addIntentListener("QuoteStream", async (context) => {
 
 #### See also
 
+* [Register an Intent Handler](../spec#register-an-intent-handler)
 * [`PrivateChannel`](PrivateChannel)
 * [`Listener`](Types#listener)
 * [`Context`](Types#context)
@@ -192,7 +193,7 @@ createPrivateChannel(): Promise<PrivateChannel>;
 
 Returns a `Channel` with an auto-generated identity that is intended for private communication between applications. Primarily used to create channels that will be returned to other applications via an IntentResolution for a raised intent.
 
-If the `PrivateChannel` cannot be created, the returned promise MUST be rejected with an error string from the [`ChannelError`](Errors#channelerror) enumeration.
+If the `PrivateChannel` cannot be created, the returned promise MUST be rejected with an `Error` object with a `message` chosen from the [`ChannelError`](Errors#channelerror) enumeration.
 
 The `PrivateChannel` type is provided to support synchronisation of data transmitted over returned channels, by allowing both parties to listen for events denoting subscription and unsubscription from the returned channel. `PrivateChannels` are only retrievable via raising an intent.
 
@@ -247,7 +248,7 @@ Find all the available instances for a particular application.
 
 If there are no instances of the specified application the returned promise should resolve to an empty array.
 
-If the request fails for another reason, the promise will return an `Error` with a string from the `ResolveError` enumeration.
+If the request fails for another reason, the promise MUST be rejected with an `Error` Object with a `message` chosen from the `ResolveError` enumeration.
 
 #### Example
 
@@ -268,10 +269,9 @@ findIntent(intent: string, context?: Context, resultType?: string): Promise<AppI
 Find out more information about a particular intent by passing its name, and optionally its context and/or a desired result context type.
 
 `findIntent` is effectively granting programmatic access to the Desktop Agent's resolver.
-It returns a promise resolving to the intent, its metadata and metadata about the apps and app instances that are registered to handle it.
-This can be used to raise the intent against a specific app or app instance.
+It returns a promise resolving to an `AppIntent` which provides details of the intent, its metadata and metadata about the apps and app instances that are registered to handle it. This can be used to raise the intent against a specific app or app instance.
 
-If the resolution fails, the promise will return an `Error` with a string from the [`ResolveError`](Errors#resolveerror) enumeration.
+If the resolution fails, the promise MUST be rejected with an `Error` Object with a `message` chosen from the [`ResolveError`](Errors#resolveerror) enumeration. This includes the case where no apps are found that resolve the intent, when the `ResolveError.NoAppsFound` message should be used.
 
 Result types may be a type name, the string `"channel"` (which indicates that the app will return a channel) or a string indicating a channel that returns a specific type, e.g. `"channel<fdc3,instrument>"`. If intent resolution to an app returning a channel is requested, the desktop agent MUST include both apps that are registered as returning a channel and those registered as returning a channel with a specific type in the response.
 
@@ -349,7 +349,7 @@ Find all the available intents for a particular context, and optionally a desire
 `findIntentsByContext` is effectively granting programmatic access to the Desktop Agent's resolver.
 A promise resolving to all the intents, their metadata and metadata about the apps and app instances that registered as handlers is returned, based on the context types the intents have registered.
 
-If the resolution fails, the promise will return an `Error` with a string from the [`ResolveError`](Errors#resolveerror) enumeration.
+If the resolution fails, the promise MUST be rejected with an `Error` Object with a `message` chosen from the [`ResolveError`](Errors#resolveerror) enumeration. This includes the case where no intents with associated apps are found, when the `ResolveError.NoAppsFound` message should be used.
 
 The optional `resultType` argument may be a type name, the string `"channel"` (which indicates that the app will return a channel) or a string indicating a channel that returns a specific type, e.g. `"channel<fdc3,instrument>"`. If intent resolution to an app returning a channel is requested without a specified context type, the desktop agent MUST include both apps that are registered as returning a channel and those registered as returning a channel with a specific type in the response.
 
@@ -490,7 +490,7 @@ getOrCreateChannel(channelId: string): Promise<Channel>;
 
 Returns a `Channel` object for the specified channel, creating it (as an _App_ channel) if it does not exist.
 
-If the Channel cannot be created or access was denied, the returned promise MUST be rejected with an error string from the `ChannelError` enumeration.
+If the Channel cannot be created or access was denied, the returned promise MUST be rejected with an `Error` Object with a `message` chosen from the `ChannelError` enumeration.
 
 #### Example
 
@@ -541,7 +541,7 @@ If the channel already contains context that would be passed to context listener
 
 An app can only be joined to one channel at a time.
 
-Rejects with an error if the channel is unavailable or the join request is denied. The error string will be drawn from the [`ChannelError`](Errors#channelerror) enumeration.
+If an error occurs (such as the channel is unavailable or the join request is denied) the promise MUST be rejected with an `Error` Object with a `message` chosen from the [`ChannelError`](Errors#channelerror) enumeration.
 
 #### Examples
 
@@ -590,17 +590,17 @@ redChannel.addContextListener(null, channelListener);
 open(app: AppIdentifier, context?: Context): Promise<AppIdentifier>;
 ```
 
-Launches an app, specified via an [`AppIdentifier`](Metadata#appidentifier) object.
+Launches an app, specified via an [`AppIdentifier`](Types#appidentifier) object.
 
 The `open` method differs in use from [`raiseIntent`](#raiseintent).  Generally, it should be used when the target application is known but there is no specific intent.  For example, if an application is querying an App Directory, `open` would be used to open an app returned in the search results.
 
 **Note**, if the intent, context and target app name are all known, it is recommended to instead use [`raiseIntent`](#raiseintent) with the `target` argument.
 
 If a [`Context`](Types#context) object is passed in, this object will be provided to the opened application via a contextListener. The Context argument is functionally equivalent to opening the target app with no context and broadcasting the context directly to it.
 
-Returns an [`AppIdentifier`](Metadata#appidentifier) object with the `instanceId` field set to identify the instance of the application opened by this call.
+Returns an [`AppIdentifier`](Types#appidentifier) object with the `instanceId` field set to identify the instance of the application opened by this call.
 
-If opening errors, it returns an `Error` with a string from the [`OpenError`](Errors#openerror) enumeration.
+If an error occurs while opening the app, the promise MUST be rejected with an `Error` Object with a `message` chosen from the [`OpenError`](Errors#openerror) enumeration.
 
 #### Example
 
@@ -616,7 +616,7 @@ let instanceIdentifier = await fdc3.open(appIdentifier, context);
 #### See also
 
 * [`Context`](Types#context)
-* [`AppIdentifier`](Metadata#AppIdentifier)
+* [`AppIdentifier`](Types#appidentifier)
 * [`AppMetadata`](Metadata#appmetadata)
 * [`OpenError`](Errors#openerror)
 
@@ -631,7 +631,7 @@ Raises a specific intent for resolution against apps registered with the desktop
 The desktop agent MUST resolve the correct app to target based on the provided intent name and context data. If multiple matching apps are found, a method for resolving the intent to a target app, such as presenting the user with a resolver UI allowing them to pick an app, SHOULD be provided.
 Alternatively, the specific app or app instance to target can also be provided. A list of valid target applications and instances can be retrieved via [`findIntent`](DesktopAgent#findintent).  
 
-If a target app for the intent cannot be found with the criteria provided or the user either closes the resolver UI or otherwise cancels resolution, an `Error` with a string from the [`ResolveError`](Errors#resolveerror) enumeration is returned. If a specific target `app` parameter was set, but either the app or app instance is not available then the `ResolveError.TargetAppUnavailable` or `ResolveError.TargetInstanceUnavailable` errors MUST be returned.
+If a target app for the intent cannot be found with the criteria provided or the user either closes the resolver UI or otherwise cancels resolution, the promise MUST be rejected with an `Error` object with a `message` chosen from the [`ResolveError`](Errors#resolveerror) enumeration. If a specific target `app` parameter was set, but either the app or app instance is not available, the promise MUST be rejected with an `Error` object with either the `ResolveError.TargetAppUnavailable` or `ResolveError.TargetInstanceUnavailable` string as its `message`.
 
 If you wish to raise an intent without a context, use the `fdc3.nothing` context type. This type exists so that apps can explicitly declare support for raising an intent without context.
 
@@ -674,8 +674,9 @@ try {
 
 #### See also
 
+* [Raising Intents](../spec#raising-intents)
 * [`Context`](Types#context)
-* [`AppIdentifier`](Metadata#AppIdentifier)
+* [`AppIdentifier`](Types#AppIdentifier)
 * [`IntentResult`](Types#intentresult)
 * [`IntentResolution`](Metadata#intentresolution)
 * [`ResolveError`](Errors#resolveerror)
@@ -696,7 +697,7 @@ Using `raiseIntentForContext` is similar to calling `findIntentsByContext`, and
 
 Returns an `IntentResolution` object, see [`raiseIntent()`](#raiseintent) for details.
 
-If a target app for the intent cannot be found with the criteria provided or the user either closes the resolver UI or otherwise cancels resolution, an `Error` with a string from the [`ResolveError`](Errors#resolveerror) enumeration is returned. If a specific target `app` parameter was set, but either the app or app instance is not available then the `ResolveError.TargetAppUnavailable` or `ResolveError.TargetInstanceUnavailable` errors MUST be returned.
+If a target intent and app cannot be found with the criteria provided or the user either closes the resolver UI or otherwise cancels resolution, the promise MUST be rejected with an `Error` object with a `message` chosen from the [`ResolveError`](Errors#resolveerror) enumeration. If a specific target `app` parameter was set, but either the app or app instance is not available, the promise MUST be rejected with an `Error` object with either the `ResolveError.TargetAppUnavailable` or `ResolveError.TargetInstanceUnavailable` string as its `message`.
 
 #### Example
 
@@ -710,9 +711,10 @@ await fdc3.raiseIntentForContext(context, targetAppIdentifier);
 
 #### See also
 
+* [Raising Intents](../spec#raising-intents)
 * [`raiseIntent()`](#raiseintent)
 * [`Context`](Types#context)
-* [`AppIdentifier`](Metadata#AppIdentifier)
+* [`AppIdentifier`](Types#appidentifier)
 * [`IntentResolution`](Metadata#intentresolution)
 * [`ResolveError`](Errors#resolveerror)
 

docs/api/ref/Errors.md

@@ -2,7 +2,7 @@
 title: Errors
 ---
 
-Some FDC3 API operations return promises that can result in errors.
+FDC3 API operations may sometimes result in an error, which must be returned to the caller. Errors should be returned by rejecting the promise returned by the API with a JavaScript `Error` object (or equivalent for the language of the implementation). The `Error` Object's message should be chosen from the appropriate Error enumeration below.
 
 ## `ChannelError`
 

docs/api/spec.md

@@ -101,7 +101,7 @@ An FDC3 Standard compliant Desktop Agent implementation **MUST**:
 - Provide a method of resolving ambiguous intents (i.e. those that might be resolved by multiple applications) or unspecified intents (calls to `raiseIntentForContext` that return multiple options), such as a resolver UI.
   - Intent resolution MUST take into account any specified input or return context types
   - Requests for resolution to apps returning a channel MUST include any apps that are registered as returning a channel with a specific type.
-- Return Errors from the [`ChannelError`](ref/Errors#channelerror), [`OpenError`](ref/Errors#openerror), [`ResolveError`](ref/Errors#resolveerror) and [`ResultError`](ref/Errors#resulterror) enumerations as appropriate.
+- Return (JavaScript or platform appropriate) Error Objects with messages from the [`ChannelError`](ref/Errors#channelerror), [`OpenError`](ref/Errors#openerror), [`ResolveError`](ref/Errors#resolveerror) and [`ResultError`](ref/Errors#resulterror) enumerations as appropriate.
 - Accept as input and return as output data structures that are compatibile with the interfaces defined in this Standard.
 - Include implementations of the following [Desktop Agent](ref/DesktopAgent) API functions, as defined in this Standard:
   - [`addContextListener`](ref/DesktopAgent#addcontextlistener)
@@ -126,6 +126,7 @@ An FDC3 Standard compliant Desktop Agent implementation **SHOULD**:
 
 - Support connection to one or more App Directories meeting the [FDC3 App Directory Standard](../app-directory/overview).
 - Qualify `appId` values received from an app directory with the hostname of the app directory server (e.g. `myAppId@name.domain.com`) [as defined in the app directory standard](../app-directory/overview#application-identifiers).
+- Allow applications to register an [`IntentHandler`](ref/Types#intenthandler) for particular Intent and Context type pairs by providing `interop.intents.listensFor` metadata in their AppD record.
 - Adopt the [recommended set of User channel definitions](#recommended-user-channel-set).
 - Ensure that context messages broadcast by an application on a channel are not delivered back to that same application if they are joined to the channel.
 - Make metadata about each context message or intent and context message received (including the app that originated the message) available to the receiving application.
@@ -135,6 +136,7 @@ An FDC3 Standard compliant Desktop Agent implementation **SHOULD**:
 An FDC3 Standard compliant Desktop Agent implementation **MAY**:
 
 - Make the Desktop Agent API available through modules, imports, or other means.
+- Support multiple routes for registration of an [`IntentHandler`](ref/Types#intenthandler) by an app to be considered during Intent resolution, including dynamic registration of apps at runtime.
 - Implement the following OPTIONAL [Desktop Agent](ref/DesktopAgent) API functions:
   - [`joinUserChannel`](ref/DesktopAgent#joinuserchannel)
   - [`leaveCurrentChannel`](ref/DesktopAgent#leavecurrentchannel)
@@ -346,7 +348,7 @@ try {
 
 ### Register an Intent Handler
 
-Applications need to let the system know the intents they can support.  Typically, this is done via registration with an [App Directory](../app-directory/spec).  It is also possible for intents to be registered at the application level as well to support ad-hoc registration which may be helpful at development time.  Although dynamic registration is not part of this specification, a Desktop Agent agent may choose to support any number of registration paths.
+Applications need to let the system know the intents they can support.  Typically, this SHOULD be done via registration with an [App Directory](../app-directory/spec) by providing `interop.intents.listensFor` metadata. However, Desktop Agent implementations MAY support dynamic registration of an [`IntentHandler`](ref/Types#intenthandler) by an app at runtime (for example, when they add an `IntentListener` via the API) to allow for ad-hoc registration which may be helpful at development time.  Although dynamic registration is not part of this specification, a Desktop Agent agent MAY choose to support any number of registration paths.
 
 When an instance of an application is launched, it is expected to add an [`IntentHandler`](ref/Types#intenthandler) function to the Desktop Agent for each intent it has registered by calling the [`fdc3.addIntentListener`](ref/DesktopAgent#addintentlistener) function of the Desktop Agent. Doing so allows the Desktop Agent to pass incoming intents and contexts to that instance of the application. Hence, if the application instance was spawned in response to the raised intent, then the Desktop Agent must wait for the relevant intent listener to be added by that instance before it can deliver the intent and context to it. In order to facilitate accurate error responses, calls to `fdc3.raiseIntent` should not return an `IntentResolution` until the intent handler has been added and the intent delivered to the target app.