diff --git a/docs/api/ref/Errors.md b/docs/api/ref/Errors.md index ad30be91a..76ab4070e 100644 --- a/docs/api/ref/Errors.md +++ b/docs/api/ref/Errors.md @@ -10,11 +10,18 @@ Some FDC3 API operations return promises that can result in errors. enum OpenError { /** Returned if the specified application is not found.*/ AppNotFound = 'AppNotFound', + /** Returned if the specified application fails to launch correctly.*/ ErrorOnLaunch = 'ErrorOnLaunch', - /** Returned if the specified application launches but fails to add a context listener in order to receive the context passed to the `fdc3.open` call.*/ + + /** Returned if the specified application launches but fails to add a context + * listener in order to receive the context passed to the `fdc3.open` call. + */ AppTimeout = 'AppTimeout', - /** Returned if the FDC3 desktop agent implementation is not currently able to handle the request.*/ + + /** Returned if the FDC3 desktop agent implementation is not currently able + * to handle the request. + */ ResolverUnavailable = 'ResolverUnavailable', } ``` @@ -22,25 +29,48 @@ enum OpenError { Contains constants representing the errors that can be encountered when calling the [`open`](DesktopAgent#open) method on the [DesktopAgent](DesktopAgent) object. #### See also + * [`DesktopAgent.open`](DesktopAgent#open) ## `ResolveError` ```typescript export enum ResolveError { - /** SHOULD be returned if no apps are available that can resolve the intent and context combination.*/ + /** SHOULD be returned if no apps are available that can resolve the intent + * and context combination. + */ NoAppsFound = 'NoAppsFound', - /** Returned if the FDC3 desktop agent implementation is not currently able to handle the request.*/ + + /** Returned if the FDC3 desktop agent implementation is not currently able + * to handle the request. + */ ResolverUnavailable = 'ResolverUnavailable', - /** Returned if the user cancelled the resolution request, for example by closing or cancelling a resolver UI.*/ + + /** Returned if the user cancelled the resolution request, for example by + * closing or cancelling a resolver UI. + */ UserCancelled = 'UserCancelledResolution', - /** SHOULD be returned if a timeout cancels an intent resolution that required user interaction. Please use `ResolverUnavailable` instead for situations where a resolver UI or similar fails.*/ + + /** SHOULD be returned if a timeout cancels an intent resolution that + * required user interaction. Please use `ResolverUnavailable` instead for + * situations where a resolver UI or similar fails. + */ ResolverTimeout = 'ResolverTimeout', - /** Returned if a specified target application is not available or a new instance of it cannot be opened. */ + + /** Returned if a specified target application is not available or a new + * instance of it cannot be opened. + */ TargetAppUnavailable = 'TargetAppUnavailable', - /** Returned if a specified target application instance is not available, for example because it has been closed. */ + + /** Returned if a specified target application instance is not available, + * for example because it has been closed. + */ TargetInstanceUnavailable = 'TargetInstanceUnavailable', - /** Returned if the intent and context could not be delivered to the selected application or instance, for example because it has not added an intent handler within a timeout.*/ + + /** Returned if the intent and context could not be delivered to the selected + * application or instance, for example because it has not added an intent + * handler within a timeout. + */ IntentDeliveryFailed = 'IntentDeliveryFailed', } ``` @@ -48,6 +78,7 @@ export enum ResolveError { Contains constants representing the errors that can be encountered when calling the [`findIntent`](DesktopAgent#findintent), [`findIntentsByContext`](DesktopAgent#findintentsbycontext), [`raiseIntent`](DesktopAgent#raiseintent) or [`raiseIntentForContext`](DesktopAgent#raiseintentforcontext) methods on the [DesktopAgent](DesktopAgent). #### See also + * [`DesktopAgent.findIntent`](DesktopAgent#findintent) * [`DesktopAgent.findIntentsByContext`](DesktopAgent#findintentsbycontext) * [`DesktopAgent.raiseIntent`](DesktopAgent#raiseintent) @@ -57,9 +88,14 @@ Contains constants representing the errors that can be encountered when calling ```typescript enum ResultError { - /** Returned if the intent handler exited without returning a Promise or that Promise was not resolved with a Context or Channel object. */ + /** Returned if the intent handler exited without returning a Promise or that + * Promise was not resolved with a Context or Channel object. + */ NoResultReturned = 'NoResultReturned', - /** Returned if the Intent handler function processing the raised intent throws an error or rejects the Promise it returned. */ + + /** Returned if the Intent handler function processing the raised intent + * throws an error or rejects the Promise it returned. + */ IntentHandlerRejected = 'IntentHandlerRejected', } ``` @@ -67,6 +103,7 @@ enum ResultError { Contains constants representing the errors that can be encountered when calling the [`getResult`](DesktopAgent#findintent) method on the [IntentResolution](Metadata#intentresolution) Object. #### See also + * [`DesktopAgent.addIntentListener`](DesktopAgent#addintentlistener) * [`DesktopAgent.raiseIntent`](DesktopAgent#raiseintent) * [`IntentResolution`](Metadata#intentresolution) @@ -75,11 +112,20 @@ Contains constants representing the errors that can be encountered when calling ```typescript enum ChannelError { - /** Returned if the specified channel is not found when attempting to join a channel via the `joinUserChannel` function of the DesktopAgent (`fdc3`).*/ + /** Returned if the specified channel is not found when attempting to join a + * channel via the `joinUserChannel` function of the DesktopAgent (`fdc3`). + */ NoChannelFound = 'NoChannelFound', - /** SHOULD be returned when a request to join a user channel or to a retrieve a Channel object via the `joinUserChannel` or `getOrCreateChannel` methods of the DesktopAgent (`fdc3`) object is denied. */ + + /** SHOULD be returned when a request to join a user channel or to a retrieve + * a Channel object via the `joinUserChannel` or `getOrCreateChannel` methods + * of the DesktopAgent (`fdc3`) object is denied. + */ AccessDenied = 'AccessDenied', - /** SHOULD be returned when a channel cannot be created or retrieved via the `getOrCreateChannel` method of the DesktopAgent (`fdc3`).*/ + + /** SHOULD be returned when a channel cannot be created or retrieved via the + * `getOrCreateChannel` method of the DesktopAgent (`fdc3`). + */ CreationFailed = 'CreationFailed', } ``` @@ -87,6 +133,7 @@ enum ChannelError { Contains constants representing the errors that can be encountered when calling channels using the [`joinUserChannel`](DesktopAgent#joinuserchannel) or [`getOrCreateChannel`](DesktopAgent#getorcreatechannel) methods, or the [`getCurrentContext`](Channel#getcurrentcontext), [`broadcast`](Channel#broadcast) or [`addContextListener`](Channel#addcontextlistener) methods on the `Channel` object. #### See also + * [`DesktopAgent.joinUserChannel`](DesktopAgent#joinuserchannel) * [`DesktopAgent.getOrCreateChannel`](DesktopAgent#getorcreatechannel) * [`Channel.broadcast`](Channel#broadcast) diff --git a/docs/api/ref/Metadata.md b/docs/api/ref/Metadata.md index a3d0d2bc3..b5a162ec7 100644 --- a/docs/api/ref/Metadata.md +++ b/docs/api/ref/Metadata.md @@ -8,8 +8,11 @@ FDC3 API operations return various types of metadata. ```ts interface AppIntent { - /** Details of the intent whose relationship to resolving applications is being described. */ + /** Details of the intent whose relationship to resolving applications is + * being described. + */ readonly intent: IntentMetadata; + /** Details of applications that can resolve the intent. */ readonly apps: Array; } @@ -30,37 +33,53 @@ For each intent, it reference the applications that support that intent. ```ts interface AppMetadata extends AppIdentifier { /** - The 'friendly' app name. - This field was used with the `open` and `raiseIntent` calls in FDC3 <2.0, which now require an `AppIdentifier` wth `appId` set. - Note that for display purposes the `title` field should be used, if set, in preference to this field. + /** + * The 'friendly' app name. This field was used with the `open` and + * `raiseIntent` calls in FDC3 <2.0, which now require an `AppIdentifier` + * with `appId` set. + * + * Note that for display purposes the `title` field should be used, if set, + * in preference to this field. */ readonly name?: string; /** The version of the application. */ readonly version?: string; - /** An optional set of, implementation specific, metadata fields that can be used to disambiguate instances, such as a window title or screen position. Must only be set if `instanceId` is set. */ + /** An optional set of, implementation specific, metadata fields that can be + * used to disambiguate instances, such as a window title or screen position. + * Must only be set if `instanceId` is set. + */ readonly instanceMetadata?: Record; - /** A more user-friendly application title that can be used to render UI elements */ + /** A more user-friendly application title that can be used to render UI + * elements. + */ readonly title?: string; - /** A tooltip for the application that can be used to render UI elements */ + /** A tooltip for the application that can be used to render UI elements. */ readonly tooltip?: string; - /** A longer, multi-paragraph description for the application that could include mark-up */ + /** A longer, multi-paragraph description for the application that could + * include mark-up. + */ readonly description?: string; - /** A list of icon URLs for the application that can be used to render UI elements */ + /** 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 */ + /** A list of image URLs for the application that can be used to render UI + * elements. + */ readonly images?: Array; /** The type of result 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"). */ + * 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; } ``` @@ -109,16 +128,17 @@ Metadata relating to a context or intent & context received through the `addCont ```ts interface DisplayMetadata { /** - * A user-readable name for this channel, e.g: `"Red"` - */ + * A user-readable name for this channel, e.g: `"Red"`. */ readonly name?: string; + /** - * The color that should be associated within this channel when displaying this channel in a UI, e.g: `#FF0000`. May be any color value supported by CSS, e.g. name, hex, rgba, etc.. - */ + * The color that should be associated within this channel when displaying + * this channel in a UI, e.g: `#FF0000`. May be any color value supported by + * CSS, e.g. name, hex, rgba, etc.. */ readonly color?: string; + /** - * A URL of an image that can be used to display this channel - */ + * A URL of an image that can be used to display this channel. */ readonly glyph?: string; } ``` @@ -181,18 +201,24 @@ The media type of the icon. If not provided the Desktop Agent may refer to the s ```ts interface ImplementationMetadata { - /** The version number of the FDC3 specification that the implementation provides. - * The string must be a numeric semver version, e.g. 1.2 or 1.2.1. + /** The version number of the FDC3 specification that the implementation + * provides. The string must be a numeric semver version, e.g. 1.2 or 1.2.1. */ readonly fdc3Version: string; - /** The name of the provider of the FDC3 Desktop Agent Implementation (e.g. Finsemble, Glue42, OpenFin etc.). */ + /** The name of the provider of the FDC3 Desktop Agent Implementation + * (e.g.Finsemble, Glue42, OpenFin etc.). + */ readonly provider: string; - - /** The version of the provider of the FDC3 Desktop Agent Implementation (e.g. 5.3.0). */ + + /** The version of the provider of the FDC3 Desktop Agent Implementation + * (e.g. 5.3.0). + */ readonly providerVersion?: string; - /** The calling application instance's own metadata, according to the Desktop Agent (MUST include at least the `appId` and `instanceId`). */ + /** The calling application instance's own metadata, according to the + * Desktop Agent (MUST include at least the `appId` and `instanceId`). + */ readonly appMetadata: AppMetadata; } ``` @@ -208,9 +234,12 @@ Metadata relating to the FDC3 [DesktopAgent](DesktopAgent) object and its provid ```ts interface IntentMetadata { - /** The unique name of the intent that can be invoked by the raiseIntent call */ + /** The unique name of the intent that can be invoked by the raiseIntent call. */ readonly name: string; - /** A friendly display name for the intent that should be used to render UI elements */ + + /** A friendly display name for the intent that should be used to render UI + * elements. + */ readonly displayName: string; } ``` @@ -226,35 +255,34 @@ The interface used to describe an intent within the platform. ```ts interface IntentResolution { - /** - * Metadata about the app instance that was selected (or started) to resolve the intent. - * `source.instanceId` MUST be set, indicating the specific app instance that - * received the intent. + /** Metadata about the app instance that was selected (or started) to resolve + * the intent. `source.instanceId` MUST be set, indicating the specific app + * instance that received the intent. */ readonly source: AppMetadata; - /** - * The intent that was raised. May be used to determine which intent the user - * chose in response to `fdc3.raiseIntentForContext()`. + + /** The intent that was raised. May be used to determine which intent the user + * chose in response to `fdc3.raiseIntentForContext()`. */ readonly intent: string; - /** - * The version number of the Intents schema being used. + + /** The version number of the Intents schema being used. */ readonly version?: string; - /** - * Retrieves a promise that will resolve to either `Context` data returned - * by the application that resolves the raised intent or a `Channel` - * established and returned by the app resolving the intent. + + /** Retrieves a promise that will resolve to either `Context` data returned + * by the application that resolves the raised intent or a `Channel` + * established and returned by the app resolving the intent. * - * A `Channel` returned MAY be of the `PrivateChannel` type. The - * client can then `addContextListener()` on that channel to, for example, - * receive a stream of data. + * A `Channel` returned MAY be of the `PrivateChannel` type. The + * client can then `addContextListener()` on that channel to, for example, + * receive a stream of data. * - * If an error occurs (i.e. an error is thrown by the handler function, - * the promise it returns is rejected, or a promise is not returned by the - * handler function) then the Desktop Agent MUST reject the promise returned - * by the `getResult()` function of the `IntentResolution` with a string from - * the `ResultError` enumeration. + * If an error occurs (i.e. an error is thrown by the handler function, + * the promise it returns is rejected, or a promise is not returned by the + * handler function) then the Desktop Agent MUST reject the promise returned + * by the `getResult()` function of the `IntentResolution` with a string from + * the `ResultError` enumeration. */ getResult(): Promise; } @@ -265,7 +293,7 @@ IntentResolution provides a standard format for data returned upon resolving an #### Examples ```js -//resolve a "Chain" type intent +// Resolve a "Chain" type intent let resolution = await agent.raiseIntent("intentName", context); // Use metadata about the resolving app instance to target a further intent @@ -273,12 +301,12 @@ try { const resolution = await fdc3.raiseIntent('StageOrder', context); ... - //some time later + //Some time later await agent.raiseIntent("UpdateOrder", context, resolution.source); } catch (err) { ... } -//resolve a "Client-Service" type intent with a data or channel response +//Resolve a "Client-Service" type intent with a data or channel response let resolution = await agent.raiseIntent("intentName", context); try { const result = await resolution.getResult(); diff --git a/docs/api/ref/Types.md b/docs/api/ref/Types.md index 190b8cef8..36d89975d 100644 --- a/docs/api/ref/Types.md +++ b/docs/api/ref/Types.md @@ -12,9 +12,14 @@ If the `instanceId` field is set then the `AppMetadata` object represents a spec ```ts interface AppIdentifier { - /** The unique application identifier located within a specific application directory instance. An example of an appId might be 'app@sub.root' */ + /** The unique application identifier located within a specific application + * directory instance. An example of an appId might be 'app@sub.root'. + */ readonly appId: string; - /** An optional instance identifier, indicating that this object represents a specific instance of the application described.*/ + + /** An optional instance identifier, indicating that this object represents a + * specific instance of the application described. + */ readonly instanceId?: string; } ``` @@ -101,7 +106,7 @@ Optional metadata about the intent & context message, including the app that ori type IntentResult = Context | Channel; ``` -Describes results that an Intent handler may optionally return that should be communicated back to the app that raised the intent, via the [`IntentResolution`](Metadata#intentresolution). +Describes results that an Intent handler may optionally return that should be communicated back to the app that raised the intent, via the [`IntentResolution`](Metadata#intentresolution). Represented as a union type in TypeScript, however, this type may be rendered as an interface in other languages that both the `Context` and `Channel` types implement, allowing either to be returned by an `IntentHandler`.