Merge pull request #507 from ChartIQ/284-intent-resolution-should-con…

…tain-intent

284 IntentResolution should contain the intent raised

CHANGELOG.md

@@ -11,6 +11,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Added support for raiseIntent without a context via the addition of the `fdc3.nothing` context type ([#375](https://github.com/finos/FDC3/pull/375))
 * Added [**FDC3 Workbench**](https://fdc3.finos.org/toolbox/fdc3-workbench/), an FDC3 API developer application ([#457](https://github.com/finos/FDC3/pull/457))
 * 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))
+* `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))
 
 ### Changed
 * Consolidated `Listener` documentation with other types ([#404](https://github.com/finos/FDC3/pull/404))

docs/api/ref/Metadata.md

@@ -126,12 +126,23 @@ The Interface used to describe an Intent within the platform.
 
 ```ts
 interface IntentResolution {
-  source: TargetApp;
   /**
-  * @deprecated not assignable from intent listeners
-  */
-  data?: object;
-  version: string;
+   * The application that resolved the intent.
+   */
+  readonly source: TargetApp;
+  /**
+   * The intent that was raised. May be used to determine which intent the user
+   * chose in response to `fdc3.raiseIntentForContext()`.
+   */
+  readonly intent: string;
+  /**
+   * @deprecated not assignable from intent listeners
+   */
+  readonly data?: object;
+  /**
+   * The version number of the Intents schema being used.
+   */
+  readonly version?: string;
 }
 ```
 

docs/api/spec.md

@@ -129,39 +129,50 @@ and include a more robust mechanism for intents that need to return data back to
 
 If the raising of the intent resolves (or rejects), a standard object will be passed into the resolver function with the following format:
 
-```js
-{
-    source: String;
-    data?: Object;
-    version: String;
+```ts
+interface IntentResolution {
+  /**
+   * The application that resolved the intent.
+   */
+  readonly source: TargetApp;
+  /**
+   * The intent that was raised. May be used to determine which intent the user
+   * chose in response to `fdc3.raiseIntentForContext()`.
+   */
+  readonly intent: string;
+  /**
+   * @deprecated not assignable from intent listeners
+   */
+  readonly data?: object;
+  /**
+   * The version number of the Intents schema being used.
+   */
+  readonly version?: string;
 }
 ```
-- *source* = identifier for the Application resolving the intent (null if the intent could not be resolved)
-- *data* = return data structure - if one is provided for the given intent
-- *version* = the version number of the Intents schema being used
-
 
 For example, to raise a specific Intent:
 
 ```js
 try {
     const result = await fdc3.raiseIntent('StageOrder', context);
 }
-catch (er){
-    console.log(er.message);
+catch (err){
+    console.log(err.message);
 }
 ```
 
 or to raise an unspecified Intent for a specific context, where the user will select an intent from a resolver dialog:
 ```js
 try {
     const result = await fdc3.raiseIntentForContext(context);
+    console.log(`User raised intent: ${result.intent}`)
     if (result.data) {
         const orderId = result.data.id;
     }
 }
-catch (er){
-    console.log(er.message);
+catch (err){
+    console.log(err.message);
 }
 ```
 

src/api/IntentResolution.ts

@@ -16,10 +16,21 @@ import { TargetApp } from './Types';
  * ```
  */
 export interface IntentResolution {
+  /**
+   * The application that resolved the intent.
+   */
   readonly source: TargetApp;
+  /**
+   * The intent that was raised. May be used to determine which intent the user
+   * chose in response to `fdc3.raiseIntentForContext()`.
+   */
+  readonly intent: string;
   /**
    * @deprecated not assignable from intent listeners
    */
   readonly data?: object;
-  readonly version: string;
+  /**
+   * The version number of the Intents schema being used.
+   */
+  readonly version?: string;
 }