Merge pull request #1127 from finos/1107-fix-intent-result-type-in-2.0

Correcting IntentResult error in FDC3 2.0 and adding a very minor clarification to 2.1/next

Author: kriswest

docs/api/spec.md

@@ -225,7 +225,7 @@ As an alternative to raising a specific intent, you may also raise an unspecifie
 
 ### Intent Results
 
-An optional [`IntentResult`](ref/Types#intentresult) may also be returned as output by an application handling an intent. Results maybe either a single `Context` object, or a `Channel` that may be used to send a stream of responses. The [`PrivateChannel`](ref/PrivateChannel) type is provided to support synchronization 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](ref/DesktopAgent#raiseintent).
+An optional [`IntentResult`](ref/Types#intentresult) may also be returned as output by an application handling an intent. Results may be a single `Context` object, a `Channel` that may be used to send a stream of responses, or `void` (no result). The [`PrivateChannel`](ref/PrivateChannel) type is provided to support synchronization 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](ref/DesktopAgent#raiseintent).
 
 For example, an application handling a `CreateOrder` intent might return a context representing the order and including an ID, allowing the application that raised the intent to make further calls using that ID.
 

website/versioned_docs/version-2.0/api/ref/DesktopAgent.md

@@ -642,7 +642,7 @@ If you wish to raise an intent without a context, use the `fdc3.nothing` context
 
 Returns an [`IntentResolution`](Metadata#intentresolution) object with details of the app instance that was selected (or started) to respond to the intent.
 
-Issuing apps may optionally wait on the promise that is returned by the `getResult()` member of the IntentResolution. This promise will resolve when the _receiving app's_ intent handler function returns and resolves a promise. The Desktop Agent resolves the issuing app's promise with the Context object or Channel that is provided as resolution by the receiving app. The Desktop Agent MUST reject the issuing app's promise, with a string from the [`ResultError`](Errors#resulterror) enumeration, if: (1) the intent handling function's returned promise rejects, (2) the intent handling function doesn't return a promise, or (3) the returned promise resolves to an invalid type.
+Issuing apps may optionally wait on the promise that is returned by the `getResult()` member of the `IntentResolution`. This promise will resolve when the _receiving app's_ intent handler function returns and resolves a promise. The Desktop Agent resolves the issuing app's promise with the Context object, Channel object or void that is provided as resolution within the receiving app. The Desktop Agent MUST reject the issuing app's promise, with a string from the [`ResultError`](Errors#resulterror) enumeration, if: (1) the intent handling function's returned promise rejects, (2) the intent handling function doesn't return a valid response (a promise or void), or (3) the returned promise resolves to an invalid type.
 
 #### Example
 

website/versioned_docs/version-2.0/api/ref/Errors.md

@@ -122,8 +122,8 @@ Contains constants representing the errors that can be encountered when calling
 
 ```typescript
 enum ResultError {
-  /** Returned if the `IntentHandler` exited without returning a Promise or that
-   *  Promise was not resolved with a Context or Channel object. 
+  /** Returned if the intent handler exited without returning a valid result 
+   * (a promise resolving to a Context, Channel object or void).
    */
   NoResultReturned = 'NoResultReturned',
 

website/versioned_docs/version-2.0/api/ref/Metadata.md

@@ -345,9 +345,9 @@ interface IntentResolution {
    *  receive a stream of data.
    * 
    *  If an error occurs (i.e. an error is thrown by the handler function,
-   *  the promise it returns is rejected, or a promise is not returned by the
-   *  handler function) then the Desktop Agent MUST reject the promise returned
-   *  by the `getResult()` function of the `IntentResolution` with a string from
+   *  the promise it returns is rejected, or the promise resolved to an invalid 
+   *  type) then the Desktop Agent MUST reject the promise returned by the 
+   *  `getResult()` function of the `IntentResolution` with a string from
    *  the `ResultError` enumeration.
    */
    getResult(): Promise<IntentResult>;

website/versioned_docs/version-2.0/api/ref/Types.md

@@ -104,13 +104,19 @@ Optional metadata about the intent & context message, including the app that ori
 ## `IntentResult`
 
 ```typescript
-type IntentResult = Context | Channel;
+type IntentResult = Context | Channel | void;
 ```
 
 Describes results that an Intent handler may optionally return that should be communicated back to the app that raised the intent, via the [`IntentResolution`](Metadata#intentresolution).
 
 Represented as a union type in TypeScript, however, this type may be rendered as an interface in other languages that both the `Context` and `Channel` types implement, allowing either to be returned by an `IntentHandler`.
 
+:::info
+
+The original release of FDC3 2.0 contained an error in the `IntentResult` type, which omitted `void` as a valid return type. It was intended that an `IntentHandler` be able to return either `void` or a Promise that resolves to `void` and, as these are valid results, no error should be thrown by `IntentResolution.getResult()`. This was corrected in FDC3 2.1 and retrospectively corrected in FDC3 2.0.
+
+:::
+
 #### See also
 
 * [`Context`](#context)

website/versioned_docs/version-2.0/api/spec.md

@@ -222,7 +222,7 @@ As an alternative to raising a specific intent, you may also raise an unspecifie
 
 ### Intent Results
 
-An optional [`IntentResult`](ref/Types#intentresult) may also be returned as output by an application handling an intent. Results maybe either a single `Context` object, or a `Channel` that may be used to send a stream of responses. The [`PrivateChannel`](ref/PrivateChannel) type is provided to support synchronization 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](ref/DesktopAgent#raiseintent).
+An optional [`IntentResult`](ref/Types#intentresult) may also be returned as output by an application handling an intent. Results may be a single `Context` object, a `Channel` that may be used to send a stream of responses, or `void` (no result). The [`PrivateChannel`](ref/PrivateChannel) type is provided to support synchronization 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](ref/DesktopAgent#raiseintent).
 
 For example, an application handling a `CreateOrder` intent might return a context representing the order and including an ID, allowing the application that raised the intent to make further calls using that ID.
 

website/versioned_docs/version-2.1/api/spec.md

@@ -225,7 +225,7 @@ As an alternative to raising a specific intent, you may also raise an unspecifie
 
 ### Intent Results
 
-An optional [`IntentResult`](ref/Types#intentresult) may also be returned as output by an application handling an intent. Results maybe either a single `Context` object, or a `Channel` that may be used to send a stream of responses. The [`PrivateChannel`](ref/PrivateChannel) type is provided to support synchronization 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](ref/DesktopAgent#raiseintent).
+An optional [`IntentResult`](ref/Types#intentresult) may also be returned as output by an application handling an intent. Results may be a single `Context` object, a `Channel` that may be used to send a stream of responses, or `void` (no result). The [`PrivateChannel`](ref/PrivateChannel) type is provided to support synchronization 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](ref/DesktopAgent#raiseintent).
 
 For example, an application handling a `CreateOrder` intent might return a context representing the order and including an ID, allowing the application that raised the intent to make further calls using that ID.