Merge pull request #154 from nkolba/1.1-api-simple

1.1 api simple

docs/api/DesktopAgent.md

@@ -12,6 +12,21 @@ A Desktop Agent can be connected to one or more App Directories and will use dir
 
 ## Methods
 
+### `broadcast`
+```typescript
+broadcast(context: Context): void;
+```
+
+Publishes context to other apps on the desktop.
+
+#### Examples
+```javascript
+fdc3.broadcast(context);
+```
+#### See also
+* [addContextListener](#addcontextlistener)
+
+
 ### `open`
 
 ```typescript
@@ -108,19 +123,6 @@ A promise resolving to all the intents, their metadata and metadata about the ap
 #### See also
    * [`ResolveError`](Errors#resolveerror)
 
-### `broadcast`
-```typescript
-broadcast(context: Context): void;
-```
-
-Publishes context to other apps on the desktop.
-
-#### Examples
-```javascript
-agent.broadcast(context);
-```
-#### See also
-* [addContextListener](#addcontextlistener)
 
 ### `raiseIntent`
 
@@ -138,6 +140,66 @@ agent.raiseIntent("StartChat", newContext, intentR.source);
 #### See also
 * [`IntentResolution`](#intentresolution)
 
+
+
+
+### `getOrCreateChannel`
+```typescript
+getOrCreateChannel(channelId: string): Promise<Channel>;
+```
+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 channel could not be created or access was denied.
+
+#### Examples
+```javascript
+
+try {
+  let myChannel = await fdc3.getOrCreateChannel("myChannel");
+  myChannel.addContextListener(listener);
+}
+catch (err){
+  //app could not register the channel
+}
+
+```
+#### See also
+*[`Channel`](#channel)
+
+
+### `getSystemChannels`
+```typescript
+getSystemChannels() : Promise<Array<Channel>>;
+```
+Retrieves a list of the System channels available for the app to join
+
+#### See also
+*[`Channel`](#channel)
+
+### `joinChannel`
+```typescript
+joinChannel(channelId: string) : Promise<void>;
+```
+Joins the app to the specified channel.
+If an app is joined to a channel, all _fdc3.broadcast_ calls will go to the channel, and all listeners assigned via _fdc3.addContextListener_ will listen on the channel.
+An app can only be joined to one channel at a time.
+Rejects with error if the channel is unavailable or the join request is denied.
+ `Error` with a string from the [`ChannelError`](Errors#channelerror) enumeration.
+
+#### Examples
+```javascript
+  //get all system channels
+  const channels = await fdc3.getSystemChannels();
+
+  //create UI to pick from the system channels
+
+  //join the channel on selection
+  fdc3.joinChannel(selectedChannel.id);
+
+```
+#### See also
+*[`getSystemChannels`](#getSystemChannels)
+
+
 ### `addIntentListener`
 ```typescript
 addIntentListener(intent: string, handler: (context: Context) => void): Listener;
@@ -157,6 +219,9 @@ Adds a listener for incoming context broadcast from the Desktop Agent.
 * [`Listener`](#listener)
 * [`Context`](Context)
 
+
+
+
 ## Return Types
 
 ### `AppIntent`
@@ -234,3 +299,37 @@ The `unsubscribe` method on the listener object allows the application to cancel
 * [`DesktopAgent.addIntentListener`](#addintentlistener)
 * [`DesktopAgent.addContextListener`](#addcontextlistener)
 
+### `Channel`
+```typescript
+ Channel {
+  id: string;
+  type: string;
+  displayMetadata?: DisplayMetadata;
+  broadcast(context: Context): Promise<void>;
+  getCurrentContext(): Promise<Context|null>;
+  addBroadcastListener(listener: (event: {channel: Channel; context: Context}) => void): DesktopAgent.Listener;
+}
+```
+Object representing a context channel.
+* __id__ uniquely identifies the channel. It is either assigned by the desktop agent (system channel) or defined by an application (app channel)
+* __type__ may be _system_ or _app_
+* __dispalyMetadata__   DisplayMetaData can be used to provide display hints for channels intended to be visualized and selectable by end users.
+* __broadcast__  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.  `Error` with a string from the [`ChannelError`](Errors#channelerror) enumeration.
+* __getCurrentContext__ Returns the last context that was broadcast on the channel. If no context has been set on the channel, this will return `null`.  `Error` with a string from the [`ChannelError`](Errors#channelerror) enumeration.
+* __addBroadcastListener__  Event that is fired whenever a window broadcasts on this channel. The `channel` property within the event will always be this channel instance.  `Error` with a string from the [`ChannelError`](Errors#channelerror) enumeration.
+
+#### See also
+[`DisplayMetadata`](#DisplayMetadata)
+
+### `DisplayMetadata`
+```typescript
+DisplayMetadata{
+  name?: string;
+  color?: string;
+  glyph?: string;
+}
+```
+A desktop agent (typically for _system_ channels) may want to provide additional information about how a channel can be represented in a UI.  A common use case is for color linking.
+* __name__ The display name for the channel
+* __color__ A name, hex, rgba, etc that should be associated within this channel when displaying this channel in a UI
+* __glyph__  A URL of an image that can be used to display this channel

docs/api/Errors.md

@@ -36,4 +36,15 @@ Contains constants representing the errors that can be encountered when calling
 
 #### See also
 * [`DesktopAgent.findIntent`](DesktopAgent#findintent)
-* [`DesktopAgent.findIntentsByContext`](DesktopAgent#findintentsbycontext)
+* [`DesktopAgent.findIntentsByContext`](DesktopAgent#findintentsbycontext)
+
+## `ChannelError`
+
+```typescript
+enum ChannelError {
+  NoChannelFound = "NoChannelFound",
+  AccessDenied = "AccessDenied",
+  CreationFailed = "CreationFailed"
+}
+```
+Contains constants representing the errors that can be encountered when calling channels using the [`joinChannel`](DesktopAgent#joinchannel) or [`getOrCreateChannel`](DesktopAgent#getorcreatechannel) methods, or the [`getCurrentContext`](DesktopAgent#channel), [`broadcast`](DesktopAgent#channel) or [`addBroadcastListener`](DesktopAgent#channel) methods on the Channel object.

docs/api/api-spec.md

@@ -138,31 +138,61 @@ Intents functionality is dependent on resolver functionality to map the intent t
 
 ## Context channels
 
-The context channel api allows a set of apps to share a stateful piece of data between them, and be alerted when it changes.
+Context channels allows a set of apps to share a stateful piece of data between them, and be alerted when it changes.  Use cases for channels include color linking between applications to automate the sharing of context and topic based pub/sub such as theme.
 
-There are two types of channels, which are functionally identical, but have different visibility and discoverability semantics.
+There are two types of channels, which are functionally identical, but have different visibility and discoverability semantics.  
 
 1. The 'system' ones, which have a well understood identity. One is called 'default'.
 2. The 'app' ones, which have a transient identity and need to be revealed
 
 The 'system' channels include a 'default' channel which serves as the backwards compatible layer with the 'send/broadcast context' above. There are some reserved channel names for future use. Currently this is just 'global'.
 
+### Joining Channels
+Apps can join channels.  An app can only be joined to one channel at a time.  When an app joins a channel it will automatically recieve the current context for that channel, except if the channel joined is the 'default'.
+
+When an app is joined to a channel, calls to fdc3.broadcast and listeners added through fdc3.addContextListener will be routed to that channel.  If an app is not explicitly joined to a channel, it is on the 'default' channel.  It is up to the desktop agent to determine the behavior of the 'default' channel, and if context is automaticaly broadcast over it or not.
+
+It is possible that a call to join a channel could be rejected.  If for example, the desktop agent wanted to implement controls around what data apps can access.  
+
+### Direct Listening and Broadcast on Channels
+While joining channels automates a lot of the channel behavior for an app, it has the limitation in that an app can belong to only one channel at a time.  Listening and Broadcasting to channels using the _Channel.addBroadcastListener_ and the _Channel.broadcast_ APIs provides an app with fine-grained controls for specific channels.  This is especially useful for working with dynamic _App Channels_.
+
+### Examples
 To find a system channel, one calls
 
-    let allChannels = await channels.getSystemChannels();
-    let myChannel = allChannels.find(c=>???);
+```javascript
+    //returns an array of channels
+    let allChannels = await fdc3.getSystemChannels(); 
+    let redChannel = allChannels.find(c => c.id === 'red');
+```
+#### Joining channels
+
+To join a channel. one calls
 
-To broadcast one calls
+```javascript
+    fdc3.joinChannel(redChannel.id);
+```
+
+Calling _fdc3.broadcast_ will now route context to the joined channel.
+
+#### App Channels
 
-    myChannel.broadcast(context);
+App channels are topics dynamically created by applications connected via FDC3. For example, an app may create a channel to broadcast to others data or status specific to that app.
 
-To subscribe one calls
+To get (or create) a channel reference, then interact with it
 
-    let listener = myChannel.addBroadcastListener((c,e)=>{some code});
+```javascript
+    const appChannel = await fdc3.getOrCreateChannel('my_custom_channel');
+    //get the current context of the channel
+    let current = await appChannel.getCurrentContext();
+    //add a listener
+    appChannel.addBroadcastListener(event => {...});
+    //broadcast to the channel
+    appChannel.broadcast(context);
+
+```
 
-App channels are created and obtained as thus:
 
-    let ac = await channels.getOrCreate("a-channel-name");
 
 ## APIs
 The APIs are defined in TypeScript in [src], with documentation generated in the [docs] folder.