Merge pull request #161 from rikoe/context-filtering

Add context filtering to API and improve docs

docs/api/Channel.md

@@ -0,0 +1,193 @@
+---
+id: Channel
+sidebar_label: Channel
+title: Channel
+hide_title: true
+---
+# `Channel`
+
+```ts
+class Channel {
+
+  // properties
+  id: string;
+  type: string;
+  displayMetadata?: DisplayMetadata;
+
+  // methods
+  broadcast(context: Context): Promise<void>;
+  getCurrentContext(contextType?: string): Promise<Context|null>;
+  addContextListener(handler: ContextHandler): Listener;
+  addContextListener(contextType: string, handler: ContextHandler): Listener;
+}
+```
+
+Represents a context channel that applications can join to share context data. 
+
+A channel can be either a well-known "system" channel (retrieved with [`getSystemChannels`](DesktopAgent#getsystemchannels)) or a custom "app" channel (obtained through [`getOrCreateChannel`](DesktopAgent#getorcreatechannel)).
+
+Channels each have a unique identifier, some display metadata and operations for broadcasting context to other applications, or receiving context from other applications.
+
+#### See also
+
+* [`Context`](Context)
+* [`DesktopAgent.getSystemChannels`](DesktopAgent#getsystemchannels)
+* [`DesktopAgent.getOrCreateChannel`](DesktopAgent#getorcreatechannel)
+* [`DesktopAgent.joinChannel`](DesktopAgent#joinchannel)
+
+## Properties
+
+### `id`
+
+```ts
+public readonly id: string;
+```
+
+Uniquely identifies the channel. It is either assigned by the desktop agent (system channel) or defined by an application (app channel).
+
+### `type`
+
+```ts
+public readonly type: string;
+```
+
+Can be _system_ or _app_.
+
+### `displayMetadata`
+
+```ts
+public readonly displayMetadata?: DisplayMetadata;
+```
+
+DisplayMetadata can be used to provide display hints for channels intended to be visualized and selectable by end users.
+
+#### See also
+* [`DisplayMetadata`](DisplayMetadata)
+
+## Methods
+
+### `broadcast`
+
+```typescript
+public broadcast(context: Context): Promise<void>;
+```
+
+Broadcasts a context on the channel. This function can be used without first joining the channel, allowing applications to broadcast on channels that they aren't a member of.
+
+If broadcasting fails, the promise will return an `Error` with a string from the [`ChannelError`](Errors#channelerror) enumeration.
+
+#### Example
+
+```javascript
+const instrument = {
+    type: 'fdc3.instrument',
+    id: {
+        ticker: 'AAPL'
+    }
+};
+
+try {
+    await channel.broadcast(instrument);
+} catch (err: ChannelError) {
+    // handler errror
+}
+```
+
+#### See also
+* [`ChannelError`](Errors#channelerror)
+* [`getCurrentContext`](#getcurrentcontext)
+* [`addContextListener`](#addcontextlistener)
+
+### `getCurrentContext`
+
+```ts
+public getCurrentContext(contextType?: string): Promise<Context|null>;
+```
+
+Returns the most recent context that was broadcast on the channel. If no context has been set on the channel, this will return `null`.  
+
+Optionally a _context type_ 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 most recent contexts by type, in which case it will be possible to get the most recent context of each type, but this is not necessarily guaranteed.
+
+If getting the current context fails, the promise will return an `Error` with a string from the [`ChannelError`](Errors#channelerror) enumeration.
+
+#### Examples
+
+Without specifying a context type:
+
+```ts
+try {
+    const context = await channel.getCurrentContext();
+} catch (err: ChannelError) {
+    // handler errror
+}
+```
+
+Specifying a context type:
+
+```ts
+try {
+    const contact = await channel.getCurrentContext('fdc3.contact');
+} catch (err: ChannelError) {
+    // handler errror
+}
+```
+
+#### See also
+* [`ChannelError`](Errors#channelerror)
+* [`broadcast`](#broadcast)
+* [`addContextListener`](#addcontextlistener)
+
+### `addContextListener`
+
+```ts
+public addContextListener(handler: ContextHandler): Listener;
+```
+
+Adds a listener for incoming contexts whenever a broadcast happens on the channel.
+
+```ts
+public addContextListener(contextType: string, handler: ContextHandler): Listener;
+```
+
+Adds a listener for incoming contexts of the specified _context type_ whenever a broadcast happens on this channel.
+
+#### Examples
+
+Add a listener for any context that is broadcast on the channel:
+
+```ts
+const listener = channel.addContextListener(context => {
+    if (context.type === 'fdc3.contact') {
+        // handle the contact
+    } else if (context.type === 'fdc3.instrument') => {
+        // handle the instrument
+    }
+});
+
+// later
+listener.unsubscribe();
+```
+
+Adding listeners for specific types of context that is broadcast on the channel:
+
+```ts
+const contactListener = channel.addContextListener('fdc3.contact', contact => {
+    // handle the contact
+});
+
+const instrumentListener = channel.addContextListener('fdc3.instrument', instrument => {
+    // handle the instrument
+});
+
+// later
+contactListener.unsubscribe();
+instrumentListener.unsubscribe();
+```
+
+#### See also
+* [`Listener`](Listener)
+* [`ContextHandler`](ContextHandler)
+* [`broadcast`](#broadcast)
+* [`getCurrentContext`](#addcontextlistener)

docs/api/Context.md

@@ -11,3 +11,22 @@ type Context = object;
 ```
 
 The base object that all contexts should extend.
+
+The API specification allows this to be any object, but typically this is supposed to be a context data object adhering to the [Context Data Specification](../context-spec).
+
+This means that it must at least have a `type` property that indicates what type of data it represents, e.g. `'fdc3.contact'`.
+
+The `type` property of context objects is important for certain FDC3 operations, like [`Channel.getCurrentContext`](Channel#getCurrentContext) and [`DesktopAgent.addContextListener`](DesktopAgent#addContextListener), which allows you to filter contexts by their type.
+
+#### See also
+* [`ContextHandler`](ContextHandler)
+* [`DesktopAgent.open`](DesktopAgent#open)
+* [`DesktopAgent.broadcast`](DesktopAgent#broadcast)
+* [`DesktopAgent.addIntentListener`](DesktopAgent#addintentlistener)
+* [`DesktopAgent.addContextListener`](DesktopAgent#addcontextlistener)
+* [`DesktopAgent.findIntent`](DesktopAgent#findintent)
+* [`DesktopAgent.findIntentsByContext`](DesktopAgent#findintentsbycontext)
+* [`DesktopAgent.raiseIntent`](DesktopAgent#raiseintent)
+* [`Channel.broadcast`](Channel#broadcast)
+* [`Channel.getCurrentContext`](Cahnnel#getCurrentContext)
+* [`Channel.addContextListener`](Cahnnel#addContextListener)

docs/api/ContextHandler.md

@@ -0,0 +1,21 @@
+---
+id: ContextHandler
+sidebar_label: ContextHandler
+title: ContextHandler
+hide_title: true
+---
+# `ContextHandler`
+
+```typescript
+type ContextHandler = (context: Context) => void;
+```
+
+Describes a callback that handles a context event.
+
+Used when attaching listeners for context broadcasts and raised intents.
+
+#### See also
+* [`Context`](Context)
+* [`DesktopAgent.addIntentListener`](DesktopAgent#addintentlistener)
+* [`DesktopAgent.addContextListener`](DesktopAgent#addcontextlistener)
+* [`Channel.addContextListener`](Channel#addcontextlistener)