Merge pull request #1392 from finos/fdc3-for-web-impl-update

Fdc3 for web impl update

.github/ISSUE_TEMPLATE/---question.md

@@ -2,7 +2,7 @@
 name: "\U0001F917 Question"
 about: "If you have a questions about FDC3. \U0001F4AC"
 title: 'Question: '
-labels: ''
+labels: 'question'
 assignees: ''
 
 ---

CHANGELOG.md

@@ -19,9 +19,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Typescript definitions for getAgent() and related types
 * Typescript definitions for Browser Communication Protocol (BCP). These constitute the internal "wire protocol" that the "@finos/fdc3" library uses to communicate with Browser-Resident DAs.
 * Typescript definitions for Web Connection Protocol (WCP). These constitute the messages used to establish connectivity between "@finos/fdc3" and a Browser-Resident DA.
+* Added support for broadcast actions to the `fdc3.action` context type, allowing an Action to represent the broadcast of a specified context to an app or user channel. ([#1368](https://github.com/finos/FDC3/pull/1368))
 
 ### Changed
 
+* `window.fdc3` is now an optional property and may or may not be defined. Applications should now use `getAgent()` as the recommended way of retrieving a reference to the FDC3 API. ([#1386](https://github.com/finos/FDC3/pull/1386))
 * `Listener.unsubscribe()` was made async (the return type was changed from `void` to `Promise<void>`) for consistency with the rest of the API. ([#1305](https://github.com/finos/FDC3/pull/1305))
 * Added reference materials and supported platforms information for FDC3 in .NET via the [finos/fdc3-dotnet](https://github.com/finos/fdc3-dotnet) project. ([#1108](https://github.com/finos/FDC3/pull/1108))
 * The supported platforms page in the FDC3 documentation was moved into the API section as the information it provides all relates to FDC3 Desktop Agent API implementations. ([#1108](https://github.com/finos/FDC3/pull/1108))
@@ -37,6 +39,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Added missing `desktopAgent` field to ImplementationMetadata objects returned for all agents connect to a DesktopAgent bridge in Connection Step 6 connectAgentsUpdate messages and refined the schema used to collect this info in step 3 handshake. ([#1177](https://github.com/finos/FDC3/pull/1177))
 * Removed the `version` field from `IntentResolution` as there are no version fields for intents in the FDC3 API definitions and hence the field has no purpose. ([#1170](https://github.com/finos/FDC3/pull/1170))
 
+* Fixed error in the Client-side example from `PrivateChannel` and `addIntentListener` by correcting `id.symbol` to `id.ticker` to align with the `fdc3.instrument` context. ([#1314](https://github.com/finos/FDC3/pull/1314))
+
 ## [npm v2.1.1] - 2024-06-28
 
 ### Fixed

docs/agent-bridging/spec.md

@@ -836,7 +836,7 @@ And an error enumeration is created for errors related to bridging that may occu
 ```typescript
 enum BridgingError {
   /** Returned if a Desktop Agent did not return a response, via Desktop Agent Bridging,
-   * within the alloted timeout. */
+   * within the allotted timeout. */
   ResponseTimedOut = 'ResponseToBridgeTimedOut',
   /** Returned if a Desktop Agent that has been targeted by a particular request has
    * been disconnected from the Bridge before a response has been received from it. */

docs/api/ref/DesktopAgent.md

@@ -14,7 +14,7 @@ An FDC3 Desktop Agent is a desktop component (or aggregate of components) that s
 
 A Desktop Agent can be connected to one or more App Directories and will use directories for application identity and discovery. Typically, a Desktop Agent will contain the proprietary logic of a given platform, handling functionality like explicit application interop workflows where security, consistency, and implementation requirements are proprietary.
 
-For details of how implementations of the `DesktopAgent` are made available to applications please see [Supported Platforms](supported-platforms).
+For details of how implementations of the `DesktopAgent` are made available to applications please see [Supported Platforms](../supported-platforms).
 
 <Tabs groupId="lang">
 <TabItem value="ts" label="TypeScript/JavaScript">
@@ -293,7 +293,7 @@ fdc3.addIntentListener("CreateOrder", (context) => {
 //Handle a raised intent and return a PrivateChannel over which response will be sent
 fdc3.addIntentListener("QuoteStream", async (context) => {
   const channel: PrivateChannel = await fdc3.createPrivateChannel();
-  const symbol = context.id.symbol;
+  const symbol = context.id.ticker;
 
   // Called when the remote side adds a context listener
   const addContextListener = channel.onAddContextListener((contextType) => {

docs/api/ref/Errors.md

@@ -5,12 +5,11 @@ title: Errors
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-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.
+FDC3 API operations may sometimes result in an error that is returned to the caller. Errors MUST 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.
 
 ## `AgentError`
 
-Contains constants representing the errors that can be encountered when calling the [`getAgent`](getAgent) function to establish connectivity to a Desktop Agent. Primarily used with web applications, but may also be used in other language
-implementations.
+Contains constants representing the errors that can be encountered when calling the [`getAgent`](getAgent) function to establish connectivity to a Desktop Agent. Primarily used with web applications, but may also be used in other language implementations.
 
 <Tabs groupId="lang">
 <TabItem value="ts" label="TypeScript/JavaScript">
@@ -33,13 +32,13 @@ enum AgentError {
 
     /** Returned if either the failover function itself, or what it returned,  
      * was not the right type. */ 
-    InvalidFailover = "InvalidFailover" 
+    InvalidFailover = "InvalidFailover",
 } 
 ```
+
 </TabItem>
 </Tabs>
 
-
 ## `ChannelError`
 
 Contains constants representing the errors that can be encountered when calling channels using the [`joinUserChannel`](DesktopAgent#joinuserchannel) or [`getOrCreateChannel`](DesktopAgent#getorcreatechannel) methods, or the [`getCurrentContext`](Channel#getcurrentcontext), [`broadcast`](Channel#broadcast) or [`addContextListener`](Channel#addcontextlistener) methods on the `Channel` object.
@@ -52,24 +51,24 @@ 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',
+  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',
+  AccessDenied = "AccessDenied",
 
   /** SHOULD be returned when a channel cannot be created or retrieved via the
    *  `getOrCreateChannel` method of the DesktopAgent (`fdc3`).
    */
-  CreationFailed = 'CreationFailed',
+  CreationFailed = "CreationFailed",
 
   /** Returned if a call to the `broadcast` functions is made with an invalid
    *  context argument. Contexts should be Objects with at least a `type` field
    *  that has a `string` value.
    */
-  MalformedContext = 'MalformedContext',
+  MalformedContext = "MalformedContext",
 }
 ```
 
@@ -129,30 +128,30 @@ Contains constants representing the errors that can be encountered when calling
 ```ts
 enum OpenError {
   /** Returned if the specified application is not found.*/
-  AppNotFound = 'AppNotFound',
+  AppNotFound = "AppNotFound",
 
   /** Returned if the specified application fails to launch correctly.*/
-  ErrorOnLaunch = 'ErrorOnLaunch',
+  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',
+  AppTimeout = "AppTimeout",
 
   /** Returned if the FDC3 desktop agent implementation is not currently able
    *  to handle the request.
    */
-  ResolverUnavailable = 'ResolverUnavailable',
+  ResolverUnavailable = "ResolverUnavailable",
 
   /** Returned if a call to the `open` function is made with an invalid
    *  context argument. Contexts should be Objects with at least a `type` field
    *  that has a `string` value.
    */
-  MalformedContext = 'MalformedContext',
+  MalformedContext = "MalformedContext",
 
     /** @experimental Returned if the specified Desktop Agent is not found, via a connected 
    *  Desktop Agent Bridge. */
-  DesktopAgentNotFound = 'DesktopAgentNotFound',
+  DesktopAgentNotFound = "DesktopAgentNotFound",
 }
 ```
 
@@ -212,49 +211,49 @@ export enum ResolveError {
   /** SHOULD be returned if no apps are available that can resolve the intent
    *  and context combination.
    */
-  NoAppsFound = 'NoAppsFound',
+  NoAppsFound = "NoAppsFound",
 
   /** Returned if the FDC3 desktop agent implementation is not currently able
    *  to handle the request.
    */
-  ResolverUnavailable = 'ResolverUnavailable',
+  ResolverUnavailable = "ResolverUnavailable",
 
   /** Returned if the user cancelled the resolution request, for example by
    *  closing or cancelling a resolver UI.
    */
-  UserCancelled = 'UserCancelledResolution',
+  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',
+  ResolverTimeout = "ResolverTimeout",
 
   /** Returned if a specified target application is not available or a new
    *  instance of it cannot be opened. 
    */
-  TargetAppUnavailable = 'TargetAppUnavailable',
+  TargetAppUnavailable = "TargetAppUnavailable",
 
   /** Returned if a specified target application instance is not available,
    *  for example because it has been closed. 
    */
-  TargetInstanceUnavailable = 'TargetInstanceUnavailable',
+  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',
+  IntentDeliveryFailed = "IntentDeliveryFailed",
 
   /** Returned if a call to one of the `raiseIntent` functions is made with an 
    *  invalid context argument. Contexts should be Objects with at least a `type`
    *  field that has a `string` value.
    */
-  MalformedContext = 'MalformedContext',
+  MalformedContext = "MalformedContext",
 
     /** @experimental Returned if the specified Desktop Agent is not found, via a connected 
    *  Desktop Agent Bridge. */
-  DesktopAgentNotFound = 'DesktopAgentNotFound',
+  DesktopAgentNotFound = "DesktopAgentNotFound",
 }
 ```
 
@@ -339,12 +338,12 @@ enum ResultError {
   /** Returned if the intent handler exited without returning a valid result 
    * (a promise resolving to a Context, Channel object or void).
    */
-  NoResultReturned = 'NoResultReturned',
+  NoResultReturned = "NoResultReturned",
 
   /** Returned if the `IntentHandler` function processing the raised intent
    *  throws an error or rejects the Promise it returned. 
    */
-  IntentHandlerRejected = 'IntentHandlerRejected',
+  IntentHandlerRejected = "IntentHandlerRejected",
 }
 ```
 
@@ -387,21 +386,24 @@ public static class ResultError
 ```ts
 enum BridgingError {
   /** @experimental Returned if a Desktop Agent did not return a response, via 
-   *  Desktop Agent Bridging, within the alloted timeout. */
-  ResponseTimedOut = 'ResponseToBridgeTimedOut',
+   *  Desktop Agent Bridging, within the allotted timeout. */
+  ResponseTimedOut = "ResponseToBridgeTimedOut",
+
   /** @experimental Returned if a Desktop Agent that has been targeted by a 
    *  particular request has been disconnected from the Bridge before a 
    *  response has been received from it. */
-  AgentDisconnected = 'AgentDisconnected',
+  AgentDisconnected = "AgentDisconnected",
+
   /** @experimental Returned for FDC3 API calls that are specified with
    *  arguments indicating that a remote Desktop agent should be targeted
    *  (e.g. raiseIntent with an app on a remote DesktopAgent targeted), 
    *  when the local Desktop Agent is not connected to a bridge. */
-  NotConnectedToBridge = 'NotConnectedToBridge',
+  NotConnectedToBridge = "NotConnectedToBridge",
+
   /** @experimental Returned if a message to a Bridge deviates from the schema
    *  for that message sufficiently that it could not be processed.
    */
-  MalformedMessage = 'MalformedMessage'
+  MalformedMessage = "MalformedMessage",
 }
 ```