Skip to content

Commit

Permalink
Revert "Merge remote-tracking branch 'upstream/master' into 544-Deskt…
Browse files Browse the repository at this point in the history 
…op-Agent-Bridging-Proposal"

This reverts commit 5d30205, reversing
changes made to 471f90b.
  • Loading branch information
Tiago Pina committed Jul 27, 2022
1 parent a202302 commit 6d97396
Show file tree
Hide file tree
Showing 44 changed files with 293 additions and 967 deletions.
5 changes: 2 additions & 3 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
* Added a Trademarks page to website to acknowledge trademarks used within the Standard not owned by FINOS or the Linux Foundation ([#534](https://github.com/finos/FDC3/pull/534))
* Added details of FDC3's existing versioning and deprecation policies to the FDC3 compliance page ([#539](https://github.com/finos/FDC3/pull/539))
* Added a new experimental features policy, which exempts features designated as experimental from the versioning and deprecation policies, to the FDC3 compliance page ([#549](https://github.com/finos/FDC3/pull/549))
* Added a recommended set of user channel definitions to the API docs and typescript sources ([#727](https://github.com/finos/FDC3/pull/727))
* Added a recommended set of user channel definitions to the API docs and typescript sources ([#727](https://github.com/finos/FDC3/pull/726))
* Added the optional exposure of originating app metadata to messages received via `addContextListener` and `addIntentListener` via the new `ContextMetadata` type. ([#725](https://github.com/finos/FDC3/pull/725))
* Added the current app's `AppMetadata` to the `ImplementationMetadata` returned by `fdc3.getInfo()` allowing an app to retrieve its own metadata, according to the Desktop Agent ([#726](https://github.com/finos/FDC3/pull/726))
* Added a context type representing a range of time (`fdc3.timerange`). ([#706](https://github.com/finos/FDC3/pull/706))
Expand All @@ -45,7 +45,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
* Added `categories` field and recommended categories list to AppD application records to enable category based browsing of AppDs ([#673](https://github.com/finos/FDC3/pull/673))
* Added an `interop` field to AppD application records, replacing the `intents` field, to more fully describe an app's use of FDC3 and enable search for apps that 'interoperate' with a selected app ([#697](https://github.com/finos/FDC3/pull/697))
* Added `AppIdentifier` type, which is a new parent of `AppMetadata` and clarifies required fields for API call parameters which now prefer `appId` and `instanceId` over `name` ([#722](https://github.com/finos/FDC3/pull/722))
* Added a `getAppMetdata()` function to the desktop agent that can be used to retrieve the full `AppMetadata` for an `AppIdentifier` and reduced types such as `IntentResolution.source` and `ContextMetadata.source` from `AppMetadata` to `AppIdentifier` to clarify what fields a developer can rely on and that they should manually retrieve the full `AppMetadata` when they need it for display purposes. ([#751](https://github.com/finos/FDC3/pull/751))

### Changed

Expand All @@ -59,7 +58,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
* The `fdc3.joinChannel()`, `fdc3.getCurrentChannel()` and `fdc3.leaveCurrentChannel()` functions have been made optional for FDC3 API compliance, but are recommended through the application of the SHOULD keyword. ([#512](https://github.com/finos/FDC3/pull/512))
* All DesktopAgent and Channel API functions are now async for consistency, changing the return type of the `broadcast`, `addIntentListener`, `addContextListener` and `getInfo` functions ([#516](https://github.com/finos/FDC3/pull/516))
* `IntentResolution` now requires the name of the intent raised to included, allowing it to be used to determine the intent raised via `fdc3.raiseIntentForContext()`. ([#507](https://github.com/finos/FDC3/pull/507))
* The App Directory record schema (Application) has had the `manifestType` and `manifest` properties removed and replaced with the new `type` (required), `details` and `hostManifests` properties ([#437](https://github.com/finos/FDC3/pull/437))
* App Directory `images` field was replaced with `screenshots` to better align the application record with web application manifest and match its format to that used by `icons` ([#675](https://github.com/finos/FDC3/pull/675))
* API `AppMetadata` type was updated to replace the `images` field with a `screenshots` field (an array of `Image` objects) matching the spec of the App Directory's `screenshots` field entries ([#736](https://github.com/finos/FDC3/pull/736))
* App Directory endpoint for creating applications was removed as these will often be implementation dependent and should not be required for compliance ([#695](https://github.com/finos/FDC3/pull/695))
Expand Down Expand Up @@ -101,6 +99,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

* `addContextListener(contextType, handler)` now supports passing `null` as the context type ([#329](https://github.com/finos/FDC3/pull/329))
* All other API type changes and additions from the [FDC3 Standard 1.2](https://github.com/finos/FDC3/releases/tag/v1.2) release
* The Application schema by removing the `manifestType` and `manifest` properties, introducing new `type` (required), `details` and `hostManifests` properties ([#437](https://github.com/finos/FDC3/pull/437)

### Deprecated

Expand Down
107 changes: 44 additions & 63 deletions docs/api/ref/DesktopAgent.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,8 @@ It is expected that the `DesktopAgent` interface is made availabe via the [`wind
```ts
interface DesktopAgent {
// apps
open(app: AppIdentifier, context?: Context): Promise<AppIdentifier>;
findInstances(app: AppIdentifier): Promise<Array<AppIdentifier>>;
getAppMetadata(app: AppIdentifier): Promise<AppMetadata>;
open(app: AppIdentifier, context?: Context): Promise<AppMetadata>;
findInstances(app: AppIdentifier): Promise<Array<AppMetadata>>;

// context
broadcast(context: Context): Promise<void>;
Expand Down Expand Up @@ -47,7 +46,7 @@ interface DesktopAgent {
addContextListener(handler: ContextHandler): Promise<Listener>;
getSystemChannels(): Promise<Array<Channel>>;
joinChannel(channelId: string) : Promise<void>;
open(name: String, context?: Context): Promise<AppIdentifier>;
open(name: String, context?: Context): Promise<AppMetadata>;
raiseIntent(intent: string, context: Context, name: String): Promise<IntentResolution>;
raiseIntentForContext(context: Context, name: String): Promise<IntentResolution>;
}
Expand All @@ -61,7 +60,7 @@ interface DesktopAgent {
addContextListener(contextType: string | null, handler: ContextHandler): Promise<Listener>;
```

Adds a listener for incoming context broadcasts from the Desktop Agent. If the consumer is only interested in a context of a particular type, they can specify that type. If the consumer is able to receive context of any type or will inspect types received, then they can pass `null` as the `contextType` parameter to receive all context types.
Adds a listener for incoming context broadcasts from the Desktop Agent. If the consumer is only interested in a context of a particular type, they can specify that type. If the consumer is able to receive context of any type or will inspect types received, then they can pass `null` as the `contextType` parameter to receive all context types.

Context broadcasts are only received from apps that are joined to the same User Channel as the listening application, hence, if the application is not currently joined to a User Channel no broadcasts will be received. If this function is called after the app has already joined a channel and the channel already contains context that would be passed to the context listener, then it will be called immediately with that context.

Expand All @@ -78,7 +77,7 @@ const contactListener = await fdc3.addContextListener('fdc3.contact', contact =>

// listener that logs metadata for the message a specific type
const contactListener = await fdc3.addContextListener('fdc3.contact', (contact, metadata) => {
console.log(`Received context message\nContext: ${contact}\nOriginating app: ${metadata?.source}`);
console.log(`Received context message\nContext: ${contact}\nOriginating app: ${metadata?.sourceAppMetadata}`);
//do something else with the context
});
```
Expand Down Expand Up @@ -114,7 +113,7 @@ const listener = fdc3.addIntentListener('StartChat', context => {
//Handle a raised intent and log the originating app metadata
const listener = fdc3.addIntentListener('StartChat', (contact, metadata) => {
console.log(`Received intent StartChat\nContext: ${contact}\nOriginating app: ${metadata?.source}`);
console.log(`Received intent StartChat\nContext: ${contact}\nOriginating app: ${metadata?.sourceAppMetadata}`);
return;
});
Expand Down Expand Up @@ -187,14 +186,14 @@ fdc3.broadcast(instrument);
### `findInstances`
```ts
findInstances(app: AppIdentifier): Promise<Array<AppIdentifier>>;
findInstances(app: AppIdentifier): Promise<Array<AppMetadata>>;
```
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 resolution fails, the promise will return an `Error` with a string from the [`ResolveError`](Errors#resolveerror) enumeration.
#### Example
Expand Down Expand Up @@ -232,14 +231,14 @@ const appIntent = await fdc3.findIntent("StartChat");
// {
// intent: { name: "StartChat", displayName: "Chat" },
// apps: [
// { appId: "Skype" },
// { appId: "Symphony" },
// { appId: "Slack" }
// { name: "Skype" },
// { name: "Symphony" },
// { name: "Slack" }
// ]
// }
// raise the intent against a particular app
await fdc3.raiseIntent(appIntent.intent.name, context, appIntent.apps[0]);
await fdc3.raiseIntent(appIntent.intent.name, context, appIntent.apps[0].name);
//later, we want to raise 'StartChat' intent again
const appIntent = await fdc3.findIntent("StartChat");
Expand All @@ -248,10 +247,10 @@ const appIntent = await fdc3.findIntent("StartChat");
// {
// intent: { name: "StartChat", displayName: "Chat" },
// apps: [
// { appId: "Skype" },
// { appId: "Symphony" },
// { appId: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" },
// { appId: "Slack" }
// { name: "Skype" },
// { name: "Symphony" },
// { name: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" },
// { name: "Slack" }
// ]
```
Expand All @@ -270,14 +269,14 @@ const appIntent = await fdc3.findIntent("ViewContact", "fdc3.ContactList");
// returns only apps that return the specified result type:
// {
// intent: { name: "ViewContact", displayName: "View Contact Details" },
// apps: { appId: "MyCRM", resultType: "fdc3.ContactList"}]
// apps: { name: "MyCRM", resultType: "fdc3.ContactList"}]
// }
const appIntent = await fdc3.findIntent("QuoteStream", instrument, "channel<fdc3.Quote>");
// returns only apps that return a channel which will receive the specified input and result types:
// {
// intent: { name: "QuoteStream", displayName: "Quotes stream" },
// apps: { appId: "MyOMS", resultType: "channel<fdc3.Quote>"}]
// apps: { name: "MyOMS", resultType: "channel<fdc3.Quote>"}]
// }
```
Expand All @@ -298,7 +297,7 @@ A promise resolving to all the intents, their metadata and metadata about the ap
If the resolution fails, the promise will return an `Error` with a string from the [`ResolveError`](Errors#resolveerror) enumeration.
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<fdc3,instrument>"`. 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.
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<fdc3,instrument>"`. 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.
#### Example
Expand All @@ -311,20 +310,20 @@ const appIntents = await fdc3.findIntentsByContext(context);
// [
// {
// intent: { name: "StartCall", displayName: "Call" },
// apps: [{ appId: "Skype" }]
// apps: [{ name: "Skype" }]
// },
// {
// intent: { name: "StartChat", displayName: "Chat" },
// apps: [
// { appId: "Skype" },
// { appId: "Symphony" },
// { appId: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" },
// { appId: "Slack" }
// { name: "Skype" },
// { name: "Symphony" },
// { name: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" },
// { name: "Slack" }
// ]
// },
// {
// intent: { name: "ViewContact", displayName: "View Contact" },
// apps: [{ appId: "Symphony" }, { appId: "MyCRM", resultType: "fdc3.ContactList"}]
// apps: [{ name: "Symphony" }, { name: "MyCRM", resultType: "fdc3.ContactList"}]
// }
// ];
```
Expand All @@ -336,7 +335,7 @@ const appIntentsForType = await fdc3.findIntentsByContext(context, "fdc3.Contact
// returns for example:
// [{
// intent: { name: "ViewContact", displayName: "View Contact" },
// apps: [{ appId: "Symphony" }, { appId: "MyCRM", resultType: "fdc3.ContactList"}]
// apps: [{ name: "Symphony" }, { name: "MyCRM", resultType: "fdc3.ContactList"}]
// }];
// select a particular intent to raise
Expand All @@ -354,26 +353,6 @@ await fdc3.raiseIntent(startChat.intent.name, context, selectedApp);
* [`findIntent()`](#findintent)
* [`ResolveError`](Errors#resolveerror)
### `getAppMetadata`
```ts
getAppMetadata(app: AppIdentifier): Promise<AppMetadata>;
```
Retrieves the [`AppMetadata`](Metadata#appmetadata) for an [`AppIdentifier`](Types#appidentifier), which provides additional metadata (such as icons, a title and description) from the App Directory record for the application, that may be used for display purposes.
#### Examples
```js
let appIdentifier = { appId: "MyAppId@my.appd.com" }
let appMetadata = await fdc3.getAppMetadata(appIdentifier);
```
#### See also
* [`AppMetadata`](Metadata#appmetadata)
* [`AppIdentifier`](Types#appidentifier)
### `getCurrentChannel`
```ts
Expand Down Expand Up @@ -422,6 +401,7 @@ The `ImplementationMetadata` object returned also includes the metadata for the
```js
let implementationMetadata = await fdc3.getInfo();
let {appId, instanceId} = implementationMetadata.appMetadata;
```
#### See also
Expand All @@ -435,9 +415,8 @@ let {appId, instanceId} = implementationMetadata.appMetadata;
getOrCreateChannel(channelId: string): Promise<Channel>;
```
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.
Returns a `Channel` object for the specified channel, creating it (as an _App_ channel) - if it does not exist.
`Error` with a string from the [`ChannelError`](Errors#channelerror) enumeration if the channel could not be created or access was denied.
#### Example
Expand Down Expand Up @@ -587,30 +566,33 @@ redChannel.addContextListener(null, channelListener);
### `open`
```ts
open(app: AppIdentifier, context?: Context): Promise<AppIdentifier>;
open(app: AppIdentifier, context?: Context): Promise<AppMetadata>;
```
Launches an app, specified via an [`AppIdentifier`](Metadata#appidentifier) object.
Launches an app with target information, which can be either be a string like a name, or an [`AppMetadata`](Metadata#appmetadata) 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.
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 the App Directory, `open` would be used to open an app returned in the search results.
**Note**, if the intent, context and target app name are all known, it is recommended to instead use [`raiseIntent`](#raiseintent) with the `target` argument.
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 [`AppMetadata`](Metadata#appmetadata) 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`](Errors#openerror) enumeration.
#### Example
```js
// Open an app without context, using an AppIdentifier object to specify the target
let appIdentifier = { appId: 'myApp-v1.0.1' };
let instanceIdentifier = await fdc3.open(appIdentifier);
// Open an app without context, using the app name
let instanceMetadata = await fdc3.open('myApp');
// Open an app without context, using an AppMetadata object to specify the target
let appMetadata = {name: 'myApp', appId: 'myApp-v1.0.1', version: '1.0.1'};
let instanceMetadata = await fdc3.open(appMetadata);
// Open an app with context
let instanceIdentifier = await fdc3.open(appIdentifier, context);
let instanceMetadata = await fdc3.open(appMetadata, context);
```
#### See also
Expand All @@ -626,7 +608,7 @@ let instanceIdentifier = await fdc3.open(appIdentifier, context);
raiseIntent(intent: string, context: Context, app?: AppIdentifier): Promise<IntentResolution>;
```
Raises a specific intent for resolution against apps registered with the desktop agent.
Raises a specific intent for resolution against apps registered with the desktop agent.
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).
Expand Down Expand Up @@ -705,7 +687,7 @@ If a target app for the intent cannot be found with the criteria provided or the
const intentResolution = await fdc3.raiseIntentForContext(context);
// Resolve against all intents registered by a specific target app for the specified context
await fdc3.raiseIntentForContext(context, targetAppIdentifier);
await fdc3.raiseIntentForContext(context, targetAppMetadata);
```
#### See also
Expand All @@ -727,9 +709,9 @@ addContextListener(handler: ContextHandler): Promise<Listener>;
Adds a listener for incoming context broadcasts from the Desktop Agent. Provided for backwards compatibility with versions FDC3 standard <2.0.
#### See also
* [`addContextListener`](#addcontextlistener)
### `getSystemChannels` (deprecated)
```ts
Expand All @@ -738,7 +720,6 @@ getSystemChannels() : Promise<Array<Channel>>;
Alias to the [`getUserChannels`](#getuserchannels) function provided for backwards compatibility with version 1.1 & 1.2 of the FDC3 standard.
#### See also
* [`getUserChannels`](#getuserchannels)
### `joinChannel` (deprecated)
Expand All @@ -755,7 +736,7 @@ Alias to the [`joinUserChannel`](#joinuserchannel) function provided for backwar
### `open` (deprecated)
```ts
open(name: String, context?: Context): Promise<AppIdentifier>;
open(name: String, context?: Context): Promise<AppMetadata>;
```
Version of `open` that launches an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0.
Expand Down
Loading

0 comments on commit 6d97396

Please sign in to comment.