Permalink
Browse files

feat: Added typescript interface documentation

  • Loading branch information...
ColinEberhardt committed May 31, 2018
1 parent 094bc90 commit 8a5979972810aa8acc8d4e0e4a43df5507e90529
@@ -0,0 +1,3 @@
*.js
.vscode
node_modules
@@ -1,2 +1,5 @@
# API
API Working Group repository

API Working Group repository.

See the [specification draft](/Specification-Draft.md) for the current working documentation, and the [FDC3 Confluence page](https://finosfoundation.atlassian.net/wiki/spaces/FDC3) for further information.
@@ -38,104 +38,7 @@ On the financial desktop, applications often want to broadcast context to any nu
# 3. Resolvers
Intents functionality is dependent on resolver functionality to map the intent to a specific App. This will often require end-user input. Resolution can either be performed by the Desktop Agent (raising UI to pick the desired App for the intent) or by the app launching the intent - in which case the calling App will handle the resolution itself (using the resolve API below) and then invoke an explicit Intent object.
# 4. APIs
Note - these APIs are specified in pseudo-code and for convenience written in a synchronous style. Many or all implementations would be expected to be async using a Promise or callback pattern.
## 4.1 Agent Namespace

Each Desktop Agent will expose the defined APIs via namespacing of its choosing. For example, a global javascript object can be defined with the API, or the API could be imported into a local scope via a module. For the sake of illustration, the API in the examples in this spec are referred to via the (fictional) **fdc3** object.

## 4.2 open
Launches/links to an app by name.
Returns a Promise - resolving if the app is opened, rejecting if an error occurs.
```script
fdc3.open(name: String, context: Object) > Promise
```

### 4.2.1 Error States
- App not found
- Error on App launch
- App timeout
- Resolver crashed / unavailable

*Note:* open no longer takes an ‘intent’ argument. This is now moved to the more specific Intent API below.
## 4.3 resolve
Resolves a intent & context pair to a list of App names/metadata.

Resolve is effectively granting programmatic access to the Desktop Agent's resolver. Returns a promise, resolves to an Array. The resolved dataset & metadata is Desktop Agent-specific. The returned array of objects should support a Name property that is the name of the app.
```script
fdc3.resolve(intent: String, context: Object) > Promise
```
### 4.3.1 Error States
- No Apps found
- Resolver crashed / unavailable
- Timeout from Resolver

*Note:* This method could also be used by federated Desktop Agents to query for resolution from other Desktop Agents (and then aggregate results).
## 4.4 broadcast
Publishes context to other apps on the desktop.
```script
fdc3.broadcast(context: Object)
```
## 4.5 Intent Object
### 4.5.1 Constructor
```script
new fdc3.Intent(intent: String, context: Object, target: String)
```
All arguments to constructor are optional.

### 4.5.2 intent
Getter/Setter for name of the intent.
```script
Intent.intent = "...";
```

### 4.5.2 context
Getter/Setter for context data on the intent.
```script
Intent.context = {...};
```
### 4.5.3 target
Getter/Setter. Name of app to target for the Intent. Use if creating an explicit intent that bypasses resolver and goes directly to an app.

### 4.5.4 send
Dispatches the intent with the Desktop Agent. Accepts context data and target (if an explicit Intent) as optional args. Returns a Promise - resolving if the intent successfully results in launching an App, rejecting if an error state occurs.
```script
Intent.send(context: Object, target: String) > Promise
```


#### 4.5.4.1 Error States
- No Apps found
- Resolver crashed / unavailable
- Timeout from Resolver

## 4.6 IntentListener Object
Listens to incoming Intents from the Agent.
### 4.6.1 Constructor
Accepts name of Intent to handle and handler function
```script
var listen = new fdc3.IntentListener(“ViewChart”, context => {...});
```
### 4.6.2 unsubscribe
Unsubscribe the listener object.

```script
listen.unsubscribe();
```
## 4.7 ContextListener Object
Listens to incoming context broadcast from the Desktop Agent.
### 4.7.1 Constructor

Channel discovery and joining to be investigated further. Currently, this would be handled by the Desktop Agent and external to the App.
```script
var listen = new fdc3.ContextListener( handler: Function);
```
### 4.7.2 unsubscribe
Unsubscribe the listener object.

```script
listen.unsubscribe();
```

The APIs are defined in TypeScript in the [src](/src), with documentation generated in the [docs](/docs) folder.
# 5. Appendix
## 5.1 Proposed Selector Syntax
A selector syntax for app discovery and connectivity. For example:
@@ -0,0 +1,16 @@

API
===

API Working Group repository.

See the [specification draft](/Specification-Draft.md) for the current working documentation, and the [FDC3 Confluence page](https://finosfoundation.atlassian.net/wiki/spaces/FDC3) for further information.

## Index

### External modules

* ["interface"](modules/_interface_.md)

---

@@ -0,0 +1,54 @@
[fdc3-api](../README.md) > ["interface"](../modules/_interface_.md) > [OpenError](../enums/_interface_.openerror.md)

# Enumeration: OpenError

## Index

### Enumeration members

* [AppNotFound](_interface_.openerror.md#appnotfound)
* [AppTimeout](_interface_.openerror.md#apptimeout)
* [ErrorOnLaunch](_interface_.openerror.md#erroronlaunch)
* [ResolverUnavailable](_interface_.openerror.md#resolverunavailable)

---

## Enumeration members

<a id="appnotfound"></a>

### AppNotFound

**AppNotFound**: = "AppNotFound"

*Defined in interface.ts:5*

___
<a id="apptimeout"></a>

### AppTimeout

**AppTimeout**: = "AppTimeout"

*Defined in interface.ts:7*

___
<a id="erroronlaunch"></a>

### ErrorOnLaunch

**ErrorOnLaunch**: = "ErrorOnLaunch"

*Defined in interface.ts:6*

___
<a id="resolverunavailable"></a>

### ResolverUnavailable

**ResolverUnavailable**: = "ResolverUnavailable"

*Defined in interface.ts:8*

___

@@ -0,0 +1,44 @@
[fdc3-api](../README.md) > ["interface"](../modules/_interface_.md) > [ResolveError](../enums/_interface_.resolveerror.md)

# Enumeration: ResolveError

## Index

### Enumeration members

* [NoAppsFound](_interface_.resolveerror.md#noappsfound)
* [ResolverTimeout](_interface_.resolveerror.md#resolvertimeout)
* [ResolverUnavailable](_interface_.resolveerror.md#resolverunavailable)

---

## Enumeration members

<a id="noappsfound"></a>

### NoAppsFound

**NoAppsFound**: = "NoAppsFound"

*Defined in interface.ts:12*

___
<a id="resolvertimeout"></a>

### ResolverTimeout

**ResolverTimeout**: = "ResolverTimeout"

*Defined in interface.ts:14*

___
<a id="resolverunavailable"></a>

### ResolverUnavailable

**ResolverUnavailable**: = "ResolverUnavailable"

*Defined in interface.ts:13*

___

@@ -0,0 +1,30 @@
[fdc3-api](../README.md) > ["interface"](../modules/_interface_.md) > [AppMetadata](../interfaces/_interface_.appmetadata.md)

# Interface: AppMetadata

App metadata is Desktop Agent specific - but should support a name property.

## Hierarchy

**AppMetadata**

## Index

### Properties

* [name](_interface_.appmetadata.md#name)

---

## Properties

<a id="name"></a>

### name

**● name**: *`String`*

*Defined in interface.ts:36*

___

Oops, something went wrong.

0 comments on commit 8a59799

Please sign in to comment.