From 149127f03b321ab4748652460fb5fab05af55be7 Mon Sep 17 00:00:00 2001 From: Johan Sandersson <98814236+openfin-johans@users.noreply.github.com> Date: Wed, 19 Oct 2022 13:38:28 +0100 Subject: [PATCH 01/19] Adding badges for OpenFin --- website/data/community.json | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/website/data/community.json b/website/data/community.json index 15e4af1ce..ae74ba23b 100644 --- a/website/data/community.json +++ b/website/data/community.json @@ -117,7 +117,14 @@ "infoLink": "https://openfin.co/", "docsLink": "https://developers.openfin.co/of-docs", "type": "platform-provider", - "badges": [], + "badges": [ + { + "text": "FDC3 1.2 Supported" + }, + { + "text": "FDC3 2.0 Support Coming Soon" + } + ], "description": "

OpenFin founded the FDC3 standard in 2017 in collaboration with major banks and asset managers. Deployed at more than 2400 financial firms, OpenFin OS, allows applications from multiple providers to co-exist and interoperate on the desktop.

OpenFin OS consists of a secure, Chromium-based runtime called Container and a visual interface called Workspace. Workspace gets you running in no time, with themeable UI components for complex windowing, advanced search, actionable notifications and application discovery.

You can also build your own solutions using the OpenFin Container, native language adapters and APIs while remaining compatible with everything else built on OpenFin.

" }, { @@ -312,4 +319,4 @@ "type": "application-provider" } -] \ No newline at end of file +] From 8b8b8b875d49d580de593e1ad454d18c0123b86f Mon Sep 17 00:00:00 2001 From: Kris West Date: Mon, 24 Oct 2022 13:39:31 +0100 Subject: [PATCH 02/19] Fix bad links to AppIdentifier --- docs/api/ref/DesktopAgent.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index b4b4ed6c5..0b042f10a 100644 --- a/docs/api/ref/DesktopAgent.md +++ b/docs/api/ref/DesktopAgent.md @@ -598,7 +598,7 @@ The `open` method differs in use from [`raiseIntent`](#raiseintent). Generally, 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. @@ -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) @@ -712,7 +712,7 @@ await fdc3.raiseIntentForContext(context, targetAppIdentifier); * [`raiseIntent()`](#raiseintent) * [`Context`](Types#context) -* [`AppIdentifier`](Metadata#AppIdentifier) +* [`AppIdentifier`](Types#appidentifier) * [`IntentResolution`](Metadata#intentresolution) * [`ResolveError`](Errors#resolveerror) From 33abd2316a4ef7ed1e62ac9fd279d77cc8cbf281 Mon Sep 17 00:00:00 2001 From: Kris West Date: Mon, 24 Oct 2022 13:42:03 +0100 Subject: [PATCH 03/19] Fixing AppIdentifier links in 2.0 docs --- website/versioned_docs/version-2.0/api/ref/DesktopAgent.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md b/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md index c6d91418a..7d5f56b3f 100644 --- a/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md +++ b/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md @@ -617,7 +617,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) @@ -676,7 +676,7 @@ try { #### See also * [`Context`](Types#context) -* [`AppIdentifier`](Metadata#AppIdentifier) +* [`AppIdentifier`](Types#appidentifier) * [`IntentResult`](Types#intentresult) * [`IntentResolution`](Metadata#intentresolution) * [`ResolveError`](Errors#resolveerror) @@ -713,7 +713,7 @@ await fdc3.raiseIntentForContext(context, targetAppIdentifier); * [`raiseIntent()`](#raiseintent) * [`Context`](Types#context) -* [`AppIdentifier`](Metadata#AppIdentifier) +* [`AppIdentifier`](Types#appidentifier) * [`IntentResolution`](Metadata#intentresolution) * [`ResolveError`](Errors#resolveerror) From 53cf6a12acb57c3011f2a4d8a08c78c730017afb Mon Sep 17 00:00:00 2001 From: Kris West Date: Thu, 27 Oct 2022 14:16:42 +0100 Subject: [PATCH 04/19] =?UTF-8?q?=C2=96regenerate=20context=5Ftypes=20afte?= =?UTF-8?q?r=20valuation=20correction?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/context/ContextTypes.ts | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/src/context/ContextTypes.ts b/src/context/ContextTypes.ts index 40c5c8126..b86062cb3 100644 --- a/src/context/ContextTypes.ts +++ b/src/context/ContextTypes.ts @@ -188,13 +188,12 @@ export interface Position { } export interface Valuation { - CURRENCY_ISCODE?: string; + CURRENCY_ISOCODE: string; expiryTime?: Date; price?: number; type: string; valuationTime?: Date; value: number; - CURRENCY_ISOCODE: any; id?: { [key: string]: string }; name?: string; } @@ -660,13 +659,12 @@ const typeMap: any = { ), Valuation: o( [ - { json: 'CURRENCY_ISCODE', js: 'CURRENCY_ISCODE', typ: u(undefined, '') }, + { json: 'CURRENCY_ISOCODE', js: 'CURRENCY_ISOCODE', typ: '' }, { json: 'expiryTime', js: 'expiryTime', typ: u(undefined, Date) }, { json: 'price', js: 'price', typ: u(undefined, 3.14) }, { json: 'type', js: 'type', typ: '' }, { json: 'valuationTime', js: 'valuationTime', typ: u(undefined, Date) }, { json: 'value', js: 'value', typ: 3.14 }, - { json: 'CURRENCY_ISOCODE', js: 'CURRENCY_ISOCODE', typ: 'any' }, { json: 'id', js: 'id', typ: u(undefined, m('')) }, { json: 'name', js: 'name', typ: u(undefined, '') }, ], From a7a0db48deca180820a01d2f848cce1a2fcdd32d Mon Sep 17 00:00:00 2001 From: Kris West Date: Thu, 27 Oct 2022 14:19:22 +0100 Subject: [PATCH 05/19] Roll NPM module beta version number after valuation type correction --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index aa5445eef..8cd277437 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@finos/fdc3", - "version": "2.0.0-beta.2", + "version": "2.0.0-beta.3", "author": "Fintech Open Source Foundation (FINOS)", "homepage": "https://fdc3.finos.org", "repository": { From 2b6d762fc792a8fa023109557d8bf59be9805c80 Mon Sep 17 00:00:00 2001 From: Kris West Date: Fri, 28 Oct 2022 13:56:21 +0100 Subject: [PATCH 06/19] Clarifying error handling and findIntent errors in docs --- docs/api/ref/Channel.md | 4 ++-- docs/api/ref/DesktopAgent.md | 21 ++++++++--------- docs/api/ref/Errors.md | 2 +- docs/api/spec.md | 2 +- .../version-2.0/api/ref/Channel.md | 4 ++-- .../version-2.0/api/ref/DesktopAgent.md | 23 ++++++++++--------- .../version-2.0/api/ref/Errors.md | 2 +- .../versioned_docs/version-2.0/api/spec.md | 2 +- 8 files changed, 30 insertions(+), 30 deletions(-) diff --git a/docs/api/ref/Channel.md b/docs/api/ref/Channel.md index 3b391177a..5254c5418 100644 --- a/docs/api/ref/Channel.md +++ b/docs/api/ref/Channel.md @@ -132,7 +132,7 @@ public broadcast(context: Context): Promise; 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 diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index b4b4ed6c5..fd794cb48 100644 --- a/docs/api/ref/DesktopAgent.md +++ b/docs/api/ref/DesktopAgent.md @@ -192,7 +192,7 @@ createPrivateChannel(): Promise; 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 +247,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 +268,9 @@ findIntent(intent: string, context?: Context, resultType?: string): Promise"`. 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 +348,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"`. 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 +489,7 @@ getOrCreateChannel(channelId: string): Promise; 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 +540,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 @@ -600,7 +599,7 @@ If a [`Context`](Types#context) object is passed in, this object will be provide Returns an [`AppIdentifier`](Metadata#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 @@ -631,7 +630,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. @@ -696,7 +695,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 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`. #### Example diff --git a/docs/api/ref/Errors.md b/docs/api/ref/Errors.md index 8c6d5c177..22408d35d 100644 --- a/docs/api/ref/Errors.md +++ b/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` diff --git a/docs/api/spec.md b/docs/api/spec.md index e67aa6728..82d24724a 100644 --- a/docs/api/spec.md +++ b/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) diff --git a/website/versioned_docs/version-2.0/api/ref/Channel.md b/website/versioned_docs/version-2.0/api/ref/Channel.md index b29d10b56..2e5a0b0bf 100644 --- a/website/versioned_docs/version-2.0/api/ref/Channel.md +++ b/website/versioned_docs/version-2.0/api/ref/Channel.md @@ -133,7 +133,7 @@ public broadcast(context: Context): Promise; 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. @@ -174,7 +174,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 diff --git a/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md b/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md index c6d91418a..1c9675e8a 100644 --- a/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md +++ b/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md @@ -193,7 +193,7 @@ createPrivateChannel(): Promise; 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. @@ -248,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 @@ -269,10 +269,9 @@ findIntent(intent: string, context?: Context, resultType?: string): Promise"`. 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. @@ -350,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"`. 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. @@ -491,7 +490,8 @@ getOrCreateChannel(channelId: string): Promise; 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 @@ -542,7 +542,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 @@ -601,7 +601,8 @@ If a [`Context`](Types#context) object is passed in, this object will be provide Returns an [`AppIdentifier`](Metadata#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 @@ -632,7 +633,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. @@ -697,7 +698,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 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`. #### Example diff --git a/website/versioned_docs/version-2.0/api/ref/Errors.md b/website/versioned_docs/version-2.0/api/ref/Errors.md index a2addffd4..aae84ddef 100644 --- a/website/versioned_docs/version-2.0/api/ref/Errors.md +++ b/website/versioned_docs/version-2.0/api/ref/Errors.md @@ -4,7 +4,7 @@ id: version-2.0-Errors original_id: 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` diff --git a/website/versioned_docs/version-2.0/api/spec.md b/website/versioned_docs/version-2.0/api/spec.md index e3c0bfb5d..02cc3702f 100644 --- a/website/versioned_docs/version-2.0/api/spec.md +++ b/website/versioned_docs/version-2.0/api/spec.md @@ -102,7 +102,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) From 6bb99f93c7dfa9f27daf32784e41fe6eb4f1cae8 Mon Sep 17 00:00:00 2001 From: Kris West Date: Fri, 28 Oct 2022 14:15:11 +0100 Subject: [PATCH 07/19] Clarifying error handling and findIntent errors in source code comments - also syncing Channel source code comments to docs --- docs/api/ref/DesktopAgent.md | 2 +- src/api/Channel.ts | 50 ++++++++----------- src/api/DesktopAgent.ts | 20 ++++---- .../version-2.0/api/ref/DesktopAgent.md | 2 +- 4 files changed, 34 insertions(+), 40 deletions(-) diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index fd794cb48..949d97e21 100644 --- a/docs/api/ref/DesktopAgent.md +++ b/docs/api/ref/DesktopAgent.md @@ -695,7 +695,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, 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 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 diff --git a/src/api/Channel.ts b/src/api/Channel.ts index 5071b0f33..eb02b6815 100644 --- a/src/api/Channel.ts +++ b/src/api/Channel.ts @@ -30,44 +30,38 @@ export interface Channel { readonly displayMetadata?: DisplayMetadata; /** - * Broadcasts the given context on this channel. This is equivalent to joining the channel and then calling the - * top-level FDC3 `broadcast` function. - * - * Note that this function can be used without first joining the channel, allowing applications to broadcast on - * User channels that they aren't a member of. - * - * 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. - * - * `Error` with a string from the `ChannelError` enumeration. + * 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 promise will be rejected with an `Error` with a `message` string from the `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. + * + * If you are working with complex context types composed of other simpler types (as recommended by the FDC3 Context Data specification) then you should broadcast each individual type (starting with the simpler types, followed by the complex type) that you want other apps to be able to respond to. Doing so allows applications to filter the context types they receive by adding listeners for specific context types. */ broadcast(context: Context): Promise; /** - * Returns the last context that was broadcast on this channel. All channels initially have no context, until a - * context is broadcast on the channel. If there is not yet any context on the channel, this method - * will return `null`. - * - * The context of a channel will be captured regardless of how the context is broadcasted on this channel - whether - * using the top-level FDC3 `broadcast` function, or using the channel-level {@link broadcast} function on this - * object. - * - * Optionally a {@link contextType} can be provided, in which case the current context of the matching type will - * be returned (if any). Desktop agent implementations may decide to record contexts by type, in which case it will - * be possible to get the most recent context of the type specified, but this is not guaranteed. - * - * `Error` with a string from the `ChannelError` enumeration. + * When a `contextType`_` is provided, the most recent context matching the type will be returned, or `null` if no matching context is found. + * + * If no `contextType` is provided, the most recent context that was broadcast on the channel - regardless of type - will be returned. If no context has been set on the channel, it will return `null`. + * + * 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 be rejected with an `Error` with a `message` string from the `ChannelError` enumeration. */ getCurrentContext(contextType?: string): Promise; /** - * Adds a listener for incoming contexts whenever a broadcast happens on this channel. - * @deprecated use `addContextListener(null, handler)` instead of `addContextListener(handler)`. + * Adds a listener for incoming contexts of the specified _context type_ whenever a broadcast happens on this channel. + * + * 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)` function. + * + * Optional metadata about each context message received, including the app that originated the message, SHOULD be provided by the desktop agent implementation. */ - addContextListener(handler: ContextHandler): Promise; + addContextListener(contextType: string | null, handler: ContextHandler): Promise; /** - * Adds a listener for incoming contexts of the specified context type whenever a broadcast happens on this channel. + * @deprecated use `addContextListener(null, handler)` instead of `addContextListener(handler)`. */ - addContextListener(contextType: string | null, handler: ContextHandler): Promise; + addContextListener(handler: ContextHandler): Promise; } diff --git a/src/api/DesktopAgent.ts b/src/api/DesktopAgent.ts index bc8caff3f..8ed745e14 100644 --- a/src/api/DesktopAgent.ts +++ b/src/api/DesktopAgent.ts @@ -36,7 +36,7 @@ export interface DesktopAgent { * * Returns an `AppIdentifier` object with the `instanceId` field set identifying the instance of the application opened by this call. * - * If opening errors, it returns an `Error` with a string from the `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` enumeration. * * ```javascript * //Open an app without context, using an AppIdentifier object to specify the target by `appId`. @@ -56,7 +56,7 @@ export interface DesktopAgent { * It returns a promise resolving to the intent, its metadata and metadata about the apps and app instances that registered that intent. * 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` enumeration. + * If the resolution fails, the promise MUST be rejected with an `Error` Object with a `message` chosen from the `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, @@ -131,9 +131,9 @@ export interface DesktopAgent { * Find all the available intents for a particular context, and optionally a desired result context type. * * `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 instance that registered it is returned, based on the context types the intents have registered. + * 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` enumeration. + * If the resolution fails, the promise MUST be rejected with an `Error` Object with a `message` chosen from the `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 * should return a channel) or a string indicating a channel that returns a specific type, @@ -187,7 +187,7 @@ export interface DesktopAgent { * * 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. * * ```javascript * // Retrieve a list of instances of an application @@ -228,7 +228,7 @@ export interface DesktopAgent { * 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, the user MAY be presented with a Resolver UI allowing them to pick one, or another method of Resolution applied to select an app. * 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`. * - * 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` 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` 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. * @@ -278,7 +278,7 @@ export interface DesktopAgent { * * Returns an `IntentResolution` object, see `raiseIntent()` for details. * - * If a target app for the intent cannot be found with the criteria provided, an `Error` with a string from the `ResolveError` enumeration is 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` 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`. * * ```javascript * // Resolve against all intents registered for the type of the specified context @@ -381,7 +381,7 @@ export interface DesktopAgent { * * 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` 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` enumeration. * * ```javascript * // get all system channels @@ -396,7 +396,7 @@ export interface DesktopAgent { /** * 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. * * ```javascript * try { @@ -413,7 +413,7 @@ export interface DesktopAgent { /** * 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` enumeration. + * If the `PrivateChannel` cannot be created, the returned promise MUST be rejected with an `Error` object with a `message` chosen from the `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. * diff --git a/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md b/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md index 1c9675e8a..3a656636c 100644 --- a/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md +++ b/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md @@ -698,7 +698,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, 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 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 From abca5de096d86441823f0a306b361561a9e546e1 Mon Sep 17 00:00:00 2001 From: Kris West Date: Fri, 28 Oct 2022 14:15:46 +0100 Subject: [PATCH 08/19] Prettier --- src/api/Channel.ts | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/api/Channel.ts b/src/api/Channel.ts index eb02b6815..2fe0b91ed 100644 --- a/src/api/Channel.ts +++ b/src/api/Channel.ts @@ -31,31 +31,31 @@ export interface Channel { /** * 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 promise will be rejected with an `Error` with a `message` string from the `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. - * + * * If you are working with complex context types composed of other simpler types (as recommended by the FDC3 Context Data specification) then you should broadcast each individual type (starting with the simpler types, followed by the complex type) that you want other apps to be able to respond to. Doing so allows applications to filter the context types they receive by adding listeners for specific context types. */ broadcast(context: Context): Promise; /** * When a `contextType`_` is provided, the most recent context matching the type will be returned, or `null` if no matching context is found. - * + * * If no `contextType` is provided, the most recent context that was broadcast on the channel - regardless of type - will be returned. If no context has been set on the channel, it will return `null`. - * + * * 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 be rejected with an `Error` with a `message` string from the `ChannelError` enumeration. */ getCurrentContext(contextType?: string): Promise; /** * Adds a listener for incoming contexts of the specified _context type_ whenever a broadcast happens on this channel. - * + * * 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)` function. - * + * * Optional metadata about each context message received, including the app that originated the message, SHOULD be provided by the desktop agent implementation. */ addContextListener(contextType: string | null, handler: ContextHandler): Promise; @@ -63,5 +63,5 @@ export interface Channel { /** * @deprecated use `addContextListener(null, handler)` instead of `addContextListener(handler)`. */ - addContextListener(handler: ContextHandler): Promise; + addContextListener(handler: ContextHandler): Promise; } From c974395fd17587101cc098353fe93ecb7b52f17d Mon Sep 17 00:00:00 2001 From: Kris West Date: Fri, 28 Oct 2022 15:50:10 +0100 Subject: [PATCH 09/19] Clarified spec requirements for registration of intent handlers (SHOULD support in an appD record, may support other routes including dynamic registration at runtime) --- CHANGELOG.md | 1 + docs/api/ref/DesktopAgent.md | 3 +++ docs/api/spec.md | 4 +++- website/versioned_docs/version-2.0/api/ref/DesktopAgent.md | 3 +++ website/versioned_docs/version-2.0/api/spec.md | 4 +++- 5 files changed, 13 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d37c2fa5f..65078950b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -97,6 +97,7 @@ 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 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) ([#XXX](https://github.com/finos/FDC3/pull/XXX)) ## [npm v1.2.0] - 2021-04-19 diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index b4b4ed6c5..a5571988b 100644 --- a/docs/api/ref/DesktopAgent.md +++ b/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) @@ -674,6 +675,7 @@ try { #### See also +* [Raising Intents](../spec#raising-intents) * [`Context`](Types#context) * [`AppIdentifier`](Metadata#AppIdentifier) * [`IntentResult`](Types#intentresult) @@ -710,6 +712,7 @@ await fdc3.raiseIntentForContext(context, targetAppIdentifier); #### See also +* [Raising Intents](../spec#raising-intents) * [`raiseIntent()`](#raiseintent) * [`Context`](Types#context) * [`AppIdentifier`](Metadata#AppIdentifier) diff --git a/docs/api/spec.md b/docs/api/spec.md index e67aa6728..8866b00c6 100644 --- a/docs/api/spec.md +++ b/docs/api/spec.md @@ -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 application to register as Intent Handlers 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 apps as Intent handlers 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 applications as intent handlers 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. diff --git a/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md b/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md index c6d91418a..257840504 100644 --- a/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md +++ b/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md @@ -151,6 +151,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) @@ -675,6 +676,7 @@ try { #### See also +* [Raising Intents](../spec#raising-intents) * [`Context`](Types#context) * [`AppIdentifier`](Metadata#AppIdentifier) * [`IntentResult`](Types#intentresult) @@ -711,6 +713,7 @@ await fdc3.raiseIntentForContext(context, targetAppIdentifier); #### See also +* [Raising Intents](../spec#raising-intents) * [`raiseIntent()`](#raiseintent) * [`Context`](Types#context) * [`AppIdentifier`](Metadata#AppIdentifier) diff --git a/website/versioned_docs/version-2.0/api/spec.md b/website/versioned_docs/version-2.0/api/spec.md index e3c0bfb5d..cd9e6804e 100644 --- a/website/versioned_docs/version-2.0/api/spec.md +++ b/website/versioned_docs/version-2.0/api/spec.md @@ -127,6 +127,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 application to register as Intent Handlers 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. @@ -136,6 +137,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 apps as Intent handlers 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) @@ -347,7 +349,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 applications as intent handlers 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. From 45a3faaa5a0bdf58fd293e0c6d0c7c3083cdfbc8 Mon Sep 17 00:00:00 2001 From: Kris West Date: Fri, 28 Oct 2022 15:52:43 +0100 Subject: [PATCH 10/19] Clarified spec requirements for registration of intent handlers (PR num in changelog) --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 65078950b..e6ec822aa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -97,7 +97,7 @@ 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 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) ([#XXX](https://github.com/finos/FDC3/pull/XXX)) +* 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)) ## [npm v1.2.0] - 2021-04-19 From fa45df3869e0b70fcb1ab744da263a20c880c4e0 Mon Sep 17 00:00:00 2001 From: Kris West Date: Fri, 28 Oct 2022 16:01:47 +0100 Subject: [PATCH 11/19] changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index d37c2fa5f..d467295b3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -97,6 +97,8 @@ 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)) ## [npm v1.2.0] - 2021-04-19 From 99c46a18f3614d4123742d5678ed57bd6cf08aac Mon Sep 17 00:00:00 2001 From: Kris West Date: Thu, 3 Nov 2022 10:41:47 +0000 Subject: [PATCH 12/19] Apply suggestions from code review --- docs/api/spec.md | 6 +++--- website/versioned_docs/version-2.0/api/spec.md | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/api/spec.md b/docs/api/spec.md index 8866b00c6..40c201e5e 100644 --- a/docs/api/spec.md +++ b/docs/api/spec.md @@ -126,7 +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 application to register as Intent Handlers for particular Intent and Context type pairs by providing `interop.intents.listensFor` metadata in their AppD record. +- Allow application 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. @@ -136,7 +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 apps as Intent handlers to be considered during Intent resolution, including dynamic registration of apps at runtime. +- 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) @@ -348,7 +348,7 @@ try { ### Register an Intent Handler -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 applications as intent handlers 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. +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. diff --git a/website/versioned_docs/version-2.0/api/spec.md b/website/versioned_docs/version-2.0/api/spec.md index cd9e6804e..0a30c0e32 100644 --- a/website/versioned_docs/version-2.0/api/spec.md +++ b/website/versioned_docs/version-2.0/api/spec.md @@ -127,7 +127,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 application to register as Intent Handlers for particular Intent and Context type pairs by providing `interop.intents.listensFor` metadata in their AppD record. +- Allow application 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. @@ -137,7 +137,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 apps as Intent handlers to be considered during Intent resolution, including dynamic registration of apps at runtime. +- 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) @@ -349,7 +349,7 @@ try { ### Register an Intent Handler -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 applications as intent handlers 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. +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. From c7ae1108b3c008dcd3ea2ae9007ace51fedf3dba Mon Sep 17 00:00:00 2001 From: Kris West Date: Thu, 3 Nov 2022 10:46:18 +0000 Subject: [PATCH 13/19] Correct IntentHandler links --- docs/api/spec.md | 6 +++--- website/versioned_docs/version-2.0/api/spec.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/api/spec.md b/docs/api/spec.md index 40c201e5e..a9f713162 100644 --- a/docs/api/spec.md +++ b/docs/api/spec.md @@ -126,7 +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 application to register an [`IntentHandler`](/ref/Types#intenthandler) for particular Intent and Context type pairs by providing `interop.intents.listensFor` metadata in their AppD record. +- Allow application 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. @@ -136,7 +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. +- 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) @@ -348,7 +348,7 @@ try { ### Register an Intent Handler -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. +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. diff --git a/website/versioned_docs/version-2.0/api/spec.md b/website/versioned_docs/version-2.0/api/spec.md index 0a30c0e32..dee0710d5 100644 --- a/website/versioned_docs/version-2.0/api/spec.md +++ b/website/versioned_docs/version-2.0/api/spec.md @@ -349,7 +349,7 @@ try { ### Register an Intent Handler -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. +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. From 654430758058deafb8a3d66dbd027227a6f1f3b6 Mon Sep 17 00:00:00 2001 From: Kris West Date: Thu, 3 Nov 2022 12:05:22 +0000 Subject: [PATCH 14/19] Corrected schema definition for appD interop.intents.listensFor element --- CHANGELOG.md | 1 + src/app-directory/specification/appd.yaml | 3 +-- website/static/schemas/2.0/app-directory.yaml | 3 +-- website/static/schemas/next/app-directory.yaml | 3 +-- 4 files changed, 4 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d37c2fa5f..36239ae23 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -97,6 +97,7 @@ 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)) +* Corrected schema definition for appD `interop.intents.listensFor` element ([#847](https://github.com/finos/FDC3/pull/847)) ## [npm v1.2.0] - 2021-04-19 diff --git a/src/app-directory/specification/appd.yaml b/src/app-directory/specification/appd.yaml index 945a4e784..ba81c7591 100644 --- a/src/app-directory/specification/appd.yaml +++ b/src/app-directory/specification/appd.yaml @@ -650,8 +650,7 @@ components: Used to support intent resolution by desktop agents. Replaces the `intents` element used in appD records prior to FDC3 2.0. additionalProperties: x-additionalPropertiesName: Intent name - items: - $ref: '#/components/schemas/Intent' + $ref: '#/components/schemas/Intent' raises: type: object description: | diff --git a/website/static/schemas/2.0/app-directory.yaml b/website/static/schemas/2.0/app-directory.yaml index 343ced260..c82d367b6 100644 --- a/website/static/schemas/2.0/app-directory.yaml +++ b/website/static/schemas/2.0/app-directory.yaml @@ -650,8 +650,7 @@ components: Used to support intent resolution by desktop agents. Replaces the `intents` element used in appD records prior to FDC3 2.0. additionalProperties: x-additionalPropertiesName: Intent name - items: - $ref: '#/components/schemas/Intent' + $ref: '#/components/schemas/Intent' raises: type: object description: | diff --git a/website/static/schemas/next/app-directory.yaml b/website/static/schemas/next/app-directory.yaml index 945a4e784..ba81c7591 100644 --- a/website/static/schemas/next/app-directory.yaml +++ b/website/static/schemas/next/app-directory.yaml @@ -650,8 +650,7 @@ components: Used to support intent resolution by desktop agents. Replaces the `intents` element used in appD records prior to FDC3 2.0. additionalProperties: x-additionalPropertiesName: Intent name - items: - $ref: '#/components/schemas/Intent' + $ref: '#/components/schemas/Intent' raises: type: object description: | From 61767cd5b1cf52899551b09ba1567708ad9cb232 Mon Sep 17 00:00:00 2001 From: Kris West Date: Mon, 7 Nov 2022 12:27:44 +0000 Subject: [PATCH 15/19] Fixing another couple of bad links to AppIdentifier reference --- docs/api/ref/DesktopAgent.md | 4 ++-- website/versioned_docs/version-2.0/api/ref/DesktopAgent.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index 0b042f10a..b27f909d4 100644 --- a/docs/api/ref/DesktopAgent.md +++ b/docs/api/ref/DesktopAgent.md @@ -590,7 +590,7 @@ redChannel.addContextListener(null, channelListener); open(app: AppIdentifier, context?: Context): Promise; ``` -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. @@ -675,7 +675,7 @@ try { #### See also * [`Context`](Types#context) -* [`AppIdentifier`](Metadata#AppIdentifier) +* [`AppIdentifier`](Types#AppIdentifier) * [`IntentResult`](Types#intentresult) * [`IntentResolution`](Metadata#intentresolution) * [`ResolveError`](Errors#resolveerror) diff --git a/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md b/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md index 7d5f56b3f..716657eaf 100644 --- a/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md +++ b/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md @@ -591,7 +591,7 @@ redChannel.addContextListener(null, channelListener); open(app: AppIdentifier, context?: Context): Promise; ``` -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. @@ -599,7 +599,7 @@ The `open` method differs in use from [`raiseIntent`](#raiseintent). Generally, 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. From 82d422644bde59667a3c6fef94776b14c844a6a2 Mon Sep 17 00:00:00 2001 From: Kris West Date: Thu, 10 Nov 2022 10:06:56 +0000 Subject: [PATCH 16/19] Correcting AppMetadata.iamges to AppMetadata.screenshots to match documentation and appD --- src/api/AppMetadata.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/api/AppMetadata.ts b/src/api/AppMetadata.ts index c397d1e83..90e3e2034 100644 --- a/src/api/AppMetadata.ts +++ b/src/api/AppMetadata.ts @@ -40,8 +40,8 @@ export interface AppMetadata extends AppIdentifier { /** A list of icon URLs for the application that can be used to render UI elements */ readonly icons?: Array; - /** A list of image URLs for the application that can be used to render UI elements */ - readonly images?: Array; + /** Images representing the app in common usage scenarios that can be used to render UI elements */ + readonly screenshots?: Array; /** The type of output returned for any intent specified during resolution. May express a particular context type (e.g. "fdc3.instrument"), channel (e.g. "channel") or a channel that will receive a specified type (e.g. "channel"). */ readonly resultType?: string | null; From fb836ba0c47223d14c9e479428c863b02b7156c4 Mon Sep 17 00:00:00 2001 From: Kris West Date: Thu, 10 Nov 2022 10:08:31 +0000 Subject: [PATCH 17/19] rolling NPM module version number --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index aa5445eef..8cd277437 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@finos/fdc3", - "version": "2.0.0-beta.2", + "version": "2.0.0-beta.3", "author": "Fintech Open Source Foundation (FINOS)", "homepage": "https://fdc3.finos.org", "repository": { From 1653a3517971a1e5d1f033c14c961ffc9b8c2a52 Mon Sep 17 00:00:00 2001 From: Kris West Date: Thu, 10 Nov 2022 10:29:28 +0000 Subject: [PATCH 18/19] Apply suggestions from code review Co-authored-by: Hugh Troeger --- docs/api/spec.md | 2 +- website/versioned_docs/version-2.0/api/spec.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api/spec.md b/docs/api/spec.md index a9f713162..f22ae1fe6 100644 --- a/docs/api/spec.md +++ b/docs/api/spec.md @@ -126,7 +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 application to register an [`IntentHandler`](ref/Types#intenthandler) for particular Intent and Context type pairs by providing `interop.intents.listensFor` metadata in their AppD record. +- 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. diff --git a/website/versioned_docs/version-2.0/api/spec.md b/website/versioned_docs/version-2.0/api/spec.md index dee0710d5..3073ebc22 100644 --- a/website/versioned_docs/version-2.0/api/spec.md +++ b/website/versioned_docs/version-2.0/api/spec.md @@ -127,7 +127,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 application to register an [`IntentHandler`](/ref/Types#intenthandler) for particular Intent and Context type pairs by providing `interop.intents.listensFor` metadata in their AppD record. +- 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. @@ -137,7 +137,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. +- 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) From dedbf99b583aab3172e0cbcb74e068e911e57043 Mon Sep 17 00:00:00 2001 From: Kris West Date: Wed, 16 Nov 2022 13:37:43 +0000 Subject: [PATCH 19/19] Update version num in package.json --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 8cd277437..48174cb8f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@finos/fdc3", - "version": "2.0.0-beta.3", + "version": "2.0.0-beta.4", "author": "Fintech Open Source Foundation (FINOS)", "homepage": "https://fdc3.finos.org", "repository": {