Merge branch 'master' into 717-recommended-channels

Author: kriswest

CHANGELOG.md

@@ -16,13 +16,14 @@ 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 error `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))
-* 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 `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))
+* 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))
 * Added a Trademarks page to website 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))
 * Added a new experimental features policy, which exempts features designated as experimental from the versioning and deprecation policies, to the FDC3 compliance page ([#549](https://github.com/finos/FDC3/pull/549))
 * Added a recommended set of user channel definitions to the API docs and typescript sources ([#727](https://github.com/finos/FDC3/pull/726))
+* Added the optional exposure of originating app metadata to messages received via `addContextListener` and `addIntentListener` via the new `ContextMetadata` type. ([#725](https://github.com/finos/FDC3/pull/725))
 * Added the current app's `AppMetadata` to the `ImplementationMetadata` returned by `fdc3.getInfo()` allowing an app to retrieve its own metadata, according to the Desktop Agent ([#726](https://github.com/finos/FDC3/pull/726))
 * Added a context type representing a range of time (`fdc3.timerange`). ([#706](https://github.com/finos/FDC3/pull/706))
 * Added a context type representing a Currency (`fdc3.currency`). ([#708](https://github.com/finos/FDC3/pull/708))
@@ -42,6 +43,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Added `localizedVersions` field to AppD application records to support localized versions of descriptive fields in the app records and alternative launch details for localized versions of the applications themselves. ([#670](https://github.com/finos/FDC3/pull/670))
 * Added `type` and `details` elements to AppD application records to support vendor-agnostic launch details for both web and native apps ([#671](https://github.com/finos/FDC3/pull/671))
 * Added `categories` field and recommended categories list to AppD application records to enable category based browsing of AppDs ([#673](https://github.com/finos/FDC3/pull/673))
+* Added an `interop` field to AppD application records, replacing the `intents` field, to more fully describe an app's use of FDC3 and enable search for apps that 'interoperate' with a selected app ([#697](https://github.com/finos/FDC3/pull/697))
 * Added `AppIdentifier` type, which is a new parent of `AppMetadata` and clarifies required fields for API call parameters which now prefer `appId` and `instanceId` over `name` ([#722](https://github.com/finos/FDC3/pull/722))
 
 ### Changed
@@ -61,6 +63,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * App Directory endpoint for searching applications was removed as searches over multiple app directories are better implemented by retrieving all the records and searching over the resulting combined dataset ([#696](https://github.com/finos/FDC3/pull/696))
 * Extended Intent Naming conventions and added hyperlinks for existing Intent spec definitions ([#701](https://github.com/finos/FDC3/pull/701))
 * Extended recommended field type conventions for contexts to include types for ids, times, dates, currency codes and country codes. The `fdc3.country` context type was updated to comply with the recommended field name for country codes (`COUNTRY_ISOALPHA2`). ([#704](https://github.com/finos/FDC3/pull/704))
+* The `intents` field of an AppD application records has been replaced with the `interop` field, to more fully describe an app's use of FDC3 and enable search for apps that 'interoperate' with a selected app ([#697](https://github.com/finos/FDC3/pull/697))
 
 ### Deprecated
 
@@ -132,9 +135,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ### Fixed
 
 * `Intents` enum should contain `StartChat` not `StartChart` ([#364](https://github.com/finos/FDC3/pull/364))
-
-### Fixed
-
 * Return type of `getCurrentChannel()` should be `Promise<Channel | null>` ([#282](https://github.com/finos/FDC3/pull/282))
 * Missing `leaveCurrentChannel()` export ([#283](https://github.com/finos/FDC3/pull/283))
 

docs/api/ref/Channel.md

@@ -19,10 +19,12 @@ interface Channel {
   type: "user" | "app" | "private";
   displayMetadata?: DisplayMetadata;
 
-  // methods
+  // functions
   broadcast(context: Context): Promise<void>;
   getCurrentContext(contextType?: string): Promise<Context|null>;
   addContextListener(contextType: string | null, handler: ContextHandler): Promise<Listener>;
+  
+  //deprecated functions
   /**
    * @deprecated Use `addContextListener(null, handler)` instead of `addContextListener(handler)`
    */
@@ -68,8 +70,7 @@ DisplayMetadata can be used to provide display hints for User Channels intended
 
 * [`DisplayMetadata`](Metadata#displaymetadata)
 
-## Methods
-
+## Functions
 
 ### `addContextListener`
 
@@ -81,15 +82,7 @@ Adds a listener for incoming contexts of the specified _context type_ whenever a
 
 If, when this function is called, the channel already contains context that would be passed to the listener it is NOT called or passed this context automatically (this behavior differs from that of the [`fdc3.addContextListener`](DesktopAgent#addcontextlistener) function). Apps wishing to access to the current context of the channel should instead call the [`getCurrentContext(contextType)`](#getcurrentcontext) function.
 
-
-```ts
-/**
- * @deprecated Use `addContextListener(null, handler)` instead of `addContextListener(handler)`
- */
-public addContextListener(handler: ContextHandler): Promise<Listener>;
-```
-Adds a listener for incoming contexts whenever a broadcast happens on the channel.
-
+Optional metadata about each context message received, including the app that originated the message, SHOULD be provided by the desktop agent implementation.
 
 #### Examples
 
@@ -210,3 +203,19 @@ try {
 * [`broadcast`](#broadcast)
 * [`addContextListener`](#addcontextlistener)
 
+## Deprecated Functions
+
+### `addContextListener` (deprecated)
+
+```ts
+/**
+ * @deprecated Use `addContextListener(null, handler)` instead of `addContextListener(handler)`
+ */
+public addContextListener(handler: ContextHandler): Promise<Listener>;
+```
+
+Adds a listener for incoming contexts whenever a broadcast happens on the channel.
+
+#### See also
+
+* [`addContextListener`](#addcontextlistener)

docs/api/ref/DesktopAgent.md

@@ -64,6 +64,8 @@ Adds a listener for incoming context broadcasts from the Desktop Agent. If the c
 
 Context broadcasts are only received from apps that are joined to the same User Channel as the listening application, hence, if the application is not currently joined to a User Channel no broadcasts will be received. If this function is called after the app has already joined a channel and the channel already contains context that would be passed to the context listener, then it will be called immediately with that context.
 
+Optional metadata about each context message received, including the app that originated the message, SHOULD be provided by the desktop agent implementation.
+
 #### Examples
 
 ```js
@@ -72,6 +74,12 @@ const listener = await fdc3.addContextListener(null, context => { ... });
 
 // listener for a specific type
 const contactListener = await fdc3.addContextListener('fdc3.contact', contact => { ... });
+
+// listener that logs metadata for the message a specific type
+const contactListener = await fdc3.addContextListener('fdc3.contact', (contact, metadata) => { 
+  console.log(`Received context message\nContext: ${contact}\nOriginating app: ${metadata?.sourceAppMetadata}`);
+  //do something else with the context
+});
 ```
 
 #### See also
@@ -92,12 +100,20 @@ The Desktop Agent MUST reject the promise returned by the `getResult()` function
 
 The [`PrivateChannel`](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.
 
+Optional metadata about each intent & context message received, including the app that originated the message, SHOULD be provided by the desktop agent implementation.
+
 #### Examples
 
 ```js
 //Handle a raised intent
 const listener = fdc3.addIntentListener('StartChat', context => {
-    // start chat has been requested by another application
+  // start chat has been requested by another application
+  return;
+});
+
+//Handle a raised intent and log the originating app metadata
+const listener = fdc3.addIntentListener('StartChat', (contact, metadata) => { 
+  console.log(`Received intent StartChat\nContext: ${contact}\nOriginating app: ${metadata?.sourceAppMetadata}`);
     return;
 });
 
@@ -114,7 +130,7 @@ fdc3.addIntentListener("QuoteStream", async (context) => {
   const channel: PrivateChannel = await fdc3.createPrivateChannel();
   const symbol = context.id.symbol;
 
-// Called when the remote side adds a context listener
+  // Called when the remote side adds a context listener
   const addContextListener = channel.onAddContextListener((contextType) => {
     // broadcast price quotes as they come in from our quote feed
     feed.onQuote(symbol, (price) => {

docs/api/ref/Metadata.md

@@ -80,6 +80,30 @@ Note that as `AppMetadata` instances are also `AppIdentifiers` they may be passe
 * [`DesktopAgent.findIntent`](DesktopAgent#findintent)
 * [`DesktopAgent.raiseIntent`](DesktopAgent#raiseintent)
 
+## `ContextMetadata`
+
+```ts
+interface ContextMetadata {
+  /** Metadata identifying the app that sent the context and/or intent. 
+   *  @experimental
+   */
+  readonly sourceAppMetadata: AppMetadata;
+}
+```
+
+Metadata relating to a context or intent & context received through the `addContextListener` and `addIntentListener` functions. Currently identifies that originated the context or intent message.
+
+[`@experimental`](../../fdc3-compliance#experimental-features) Introduced in FDC3 2.0 and may be refined by further changes outside the normal FDC3 versioning policy.
+
+#### See also
+
+* [`AppMetadata`](#appmetadata)
+* [`ContextHandler`](Types#contexthandler)
+* [`IntentHandler`](Types#intenthandler)
+* [`addIntentListener`](DesktopAgent#addintentlistener)
+* [`addContextListener`](DesktopAgent#addcontextlistener)
+* [`Channel.addContextListener`](Channel#addcontextlistener)
+
 ## `DisplayMetadata`
 
 ```ts

docs/api/ref/Types.md

@@ -59,32 +59,38 @@ This means that it must at least have a `type` property that indicates what type
 ## `ContextHandler`
 
 ```typescript
-type ContextHandler = (context: Context) => void;
+type ContextHandler = (context: Context, metadata?: ContextMetadata) => void;
 ```
 
-Describes a callback that handles a context event.
+Describes a callback that handles a context event. Optional metadata about the context message, including the app that originated the message, may be provided.
 
 Used when attaching listeners for context broadcasts.
 
+Optional metadata about the context message, including the app that originated the message, SHOULD be provided by the desktop agent implementation.
+
 #### See also
 
 * [`Context`](#context)
+* [`ContextMetadata`](Metadata#contextmetadata)
 * [`DesktopAgent.addContextListener`](DesktopAgent#addcontextlistener)
 * [`Channel.addContextListener`](Channel#addcontextlistener)
 
 ## `IntentHandler`
 
 ```typescript
-type IntentHandler = (context: Context) => Promise<IntentResult> | void;
+type IntentHandler = (context: Context, metadata?: ContextMetadata) => Promise<IntentResult> | void;
 ```
 
 Describes a callback that handles a context event and may return a promise of a Context or Channel object to be returned to the application that raised the intent.
 
 Used when attaching listeners for raised intents.
 
+Optional metadata about the intent & context message, including the app that originated the message, SHOULD be provided by the desktop agent implementation.
+
 #### See also
 
 * [`Context`](#context)
+* [`ContextMetadata`](Metadata#contextmetadata)
 * [`PrivateChannel`](PrivateChannel)
 * [`DesktopAgent.addIntentListener`](DesktopAgent#addintentlistener)
 * [`Channel.addContextListener`](Channel#addcontextlistener)