@iebh/tera-fy 1.0.8 → 1.0.10

package/api.md

@@ -1,586 +1,600 @@
-## Classes
-
-<dl>
-<dt><a href="#TeraFy">TeraFy</a></dt>
-<dd></dd>
-<dt><a href="#TeraFyServer">TeraFyServer</a></dt>
-<dd></dd>
-<dt><a href="#User">User</a></dt>
-<dd></dd>
-<dt><a href="#Project">Project</a></dt>
-<dd></dd>
-<dt><a href="#TeraFyPlugin">TeraFyPlugin</a></dt>
-<dd></dd>
-<dt><a href="#TeraFyPluginVue">TeraFyPluginVue</a></dt>
-<dd></dd>
-</dl>
-
-## Functions
-
-<dl>
-<dt><a href="#send">send(message)</a> ⇒ <code>Promise.&lt;*&gt;</code></dt>
-<dd><p>Send a message + wait for a response object</p>
-</dd>
-<dt><a href="#sendRaw">sendRaw(message)</a></dt>
-<dd><p>Send raw message content to the server
-This function does not return or wait for a reply - use <code>send()</code> for that</p>
-</dd>
-<dt><a href="#rpc">rpc(method)</a> ⇒ <code>Promise.&lt;*&gt;</code></dt>
-<dd><p>Call an RPC function in the server instance</p>
-</dd>
-<dt><a href="#acceptMessage">acceptMessage(Raw)</a></dt>
-<dd><p>Accept an incoming message</p>
-</dd>
-<dt><a href="#toggleDevMode">toggleDevMode([devModeEnabled])</a> ⇒ <code><a href="#TeraFy">TeraFy</a></code></dt>
-<dd><p>Set or toggle devMode</p>
-</dd>
-<dt><a href="#init">init()</a></dt>
-<dd><p>Initalize the TERA client singleton</p>
-</dd>
-<dt><a href="#injectMain">injectMain()</a></dt>
-<dd><p>Find an existing active TERA server OR initalize one</p>
-</dd>
-<dt><a href="#injectStylesheet">injectStylesheet()</a></dt>
-<dd><p>Inject a local stylesheet to handle TERA server functionality</p>
-</dd>
-<dt><a href="#injectMethods">injectMethods()</a></dt>
-<dd><p>Inject all server methods defined in <code>methods</code> as local functions wrapped in the <code>rpc</code> function</p>
-</dd>
-<dt><a href="#debug">debug()</a></dt>
-<dd><p>Debugging output function
-This function will only act if <code>settings.devMode</code> is truthy</p>
-</dd>
-<dt><a href="#set">set(key, value)</a> ⇒ <code><a href="#TeraFy">TeraFy</a></code></dt>
-<dd><p>Set or merge settings
-This function also routes &#39;special&#39; keys like <code>devMode</code> to their internal handlers</p>
-</dd>
-<dt><a href="#use">use(The, [options])</a> ⇒ <code><a href="#TeraFy">TeraFy</a></code></dt>
-<dd><p>Include a TeraFy client plugin</p>
-</dd>
-<dt><a href="#toggleFocus">toggleFocus([isFocused])</a> ⇒ <code><a href="#TeraFy">TeraFy</a></code></dt>
-<dd><p>Fit the nested TERA server to a full-screen
-This is usually because the server component wants to perform some user activity like calling $prompt</p>
-</dd>
-<dt><a href="#createContext">createContext(e)</a> ⇒ <code>Object</code></dt>
-<dd><p>Create a context based on a shallow copy of this instance + additional functionality for the incoming MessageEvent
-This is used by acceptMessage to provide a means to reply / send messages to the originator</p>
-</dd>
-<dt><a href="#senderRpc">senderRpc(method)</a> ⇒ <code>Promise.&lt;*&gt;</code></dt>
-<dd><p>Request an RPC call from the original sender of a mesasge
-This function only works if the context was sub-classed via <code>createContext()</code></p>
-</dd>
-<dt><a href="#handshake">handshake()</a> ⇒ <code>Promise.&lt;Object&gt;</code></dt>
-<dd><p>Return basic server information as a form of validation</p>
-</dd>
-<dt><a href="#send">send(message)</a> ⇒ <code>Promise.&lt;*&gt;</code></dt>
-<dd><p>Send a message + wait for a response object</p>
-</dd>
-<dt><a href="#sendRaw">sendRaw(message)</a></dt>
-<dd><p>Send raw message content to the client</p>
-</dd>
-<dt><a href="#acceptMessage">acceptMessage(Raw)</a></dt>
-<dd><p>Accept a message from the parent event listener</p>
-</dd>
-<dt><a href="#requestFocus">requestFocus(cb)</a> ⇒ <code>Promise.&lt;*&gt;</code></dt>
-<dd><p>Wrapper function which runs a callback after the frontend UI has obtained focus
-This is to fix the issue where the front-end needs to switch between a regular webpage and a focused TERA iFrame wrapper
-Any use of $prompt or other UI calls should be wrapped here</p>
-</dd>
-<dt><a href="#getUser">getUser()</a> ⇒ <code><a href="#User">Promise.&lt;User&gt;</a></code></dt>
-<dd><p>Fetch the current session user</p>
-</dd>
-<dt><a href="#getProject">getProject()</a> ⇒ <code>Promise.&lt;(Project|null)&gt;</code></dt>
-<dd><p>Get the currently active project, if any</p>
-</dd>
-<dt><a href="#getProjects">getProjects()</a> ⇒ <code>Promise.&lt;Array.&lt;Project&gt;&gt;</code></dt>
-<dd><p>Get a list of projects the current session user has access to</p>
-</dd>
-<dt><a href="#setActiveProject">setActiveProject(project)</a></dt>
-<dd><p>Set the currently active project within TERA</p>
-</dd>
-<dt><a href="#requireProject">requireProject([options])</a> ⇒ <code><a href="#Project">Promise.&lt;Project&gt;</a></code></dt>
-<dd><p>Ask the user to select a project from those available - if one isn&#39;t already active
-Note that this function will percist in asking the uesr even if they try to cancel</p>
-</dd>
-<dt><a href="#selectProject">selectProject([options])</a> ⇒ <code><a href="#Project">Promise.&lt;Project&gt;</a></code></dt>
-<dd><p>Prompt the user to select a project from those available</p>
-</dd>
-<dt><a href="#getProjectState">getProjectState([options], Paths)</a> ⇒ <code>Promise.&lt;Object&gt;</code></dt>
-<dd><p>Return the current, full snapshot state of the active project</p>
-</dd>
-<dt><a href="#applyProjectStatePatch">applyProjectStatePatch()</a></dt>
-<dd><p>Apply a computed <code>just-diff</code> patch to the current project state</p>
-</dd>
-<dt><a href="#getProjectLibrary">getProjectLibrary([options])</a> ⇒ <code>Promise.&lt;Array.&lt;RefLibRef&gt;&gt;</code></dt>
-<dd><p>Fetch the active projects citation library</p>
-</dd>
-<dt><a href="#setProjectLibrary">setProjectLibrary(Collection, [options])</a> ⇒ <code>Promise</code></dt>
-<dd><p>Save back a projects citation library</p>
-</dd>
-<dt><a href="#init">init()</a></dt>
-<dd><p>Initialize the browser listener</p>
-</dd>
-<dt><a href="#debug">debug()</a></dt>
-<dd><p>Debugging output function
-This function will only act if <code>settings.devMode</code> is truthy</p>
-</dd>
-<dt><a href="#init">init()</a></dt>
-<dd><p>Optional function to be included when the main TeraFyClient is initalized</p>
-</dd>
-<dt><a href="#bindProjectState">bindProjectState([options], Paths)</a> ⇒ <code>Promies.&lt;Reactive.&lt;Object&gt;&gt;</code></dt>
-<dd><p>Return a Vue reactive object that can be read/written which whose changes will transparently be written back to the TERA server instance</p>
-</dd>
-</dl>
-
-<a name="TeraFy"></a>
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+### Table of Contents
+
+*   [TeraFy][1]
+    *   [settings][2]
+        *   [Properties][3]
+    *   [dom][4]
+        *   [Properties][5]
+    *   [methods][6]
+    *   [plugins][7]
+    *   [send][8]
+        *   [Parameters][9]
+    *   [sendRaw][10]
+        *   [Parameters][11]
+    *   [rpc][12]
+        *   [Parameters][13]
+    *   [acceptMessage][14]
+        *   [Parameters][15]
+    *   [acceptPostboxes][16]
+    *   [createProjectStatePatch][17]
+        *   [Parameters][18]
+    *   [applyProjectStatePatchLocal][19]
+        *   [Parameters][20]
+    *   [init][21]
+        *   [Parameters][22]
+    *   [detectMode][23]
+    *   [injectComms][24]
+    *   [injectStylesheet][25]
+    *   [injectMethods][26]
+    *   [debug][27]
+        *   [Parameters][28]
+    *   [set][29]
+        *   [Parameters][30]
+    *   [use][31]
+        *   [Parameters][32]
+    *   [mixin][33]
+        *   [Parameters][34]
+    *   [toggleDevMode][35]
+        *   [Parameters][36]
+    *   [toggleFocus][37]
+        *   [Parameters][38]
+*   [handshake][39]
+    *   [Properties][40]
+*   [User][41]
+    *   [Properties][42]
+*   [getUser][43]
+*   [Project][44]
+*   [getProject][45]
+*   [getProjects][46]
+*   [setActiveProject][47]
+    *   [Parameters][48]
+*   [requireProject][49]
+    *   [Parameters][50]
+*   [selectProject][51]
+    *   [Parameters][52]
+*   [getProjectState][53]
+    *   [Parameters][54]
+*   [applyProjectStatePatch][55]
+    *   [Parameters][56]
+*   [subscribeProjectState][57]
+*   [ProjectFile][58]
+    *   [Properties][59]
+*   [getProjectFiles][60]
+    *   [Parameters][61]
+*   [getProjectLibrary][62]
+    *   [Parameters][63]
+*   [setProjectLibrary][64]
+    *   [Parameters][65]
 
 ## TeraFy
-**Kind**: global class  
-<a name="new_TeraFy_new"></a>
 
-### new TeraFy()
 Main Tera-Fy Client (class singleton) to be used in a frontend browser
 
-<a name="TeraFyServer"></a>
+### settings
 
-## TeraFyServer
-**Kind**: global class  
-<a name="new_TeraFyServer_new"></a>
+Various settings to configure behaviour
 
-### new TeraFyServer()
-Server-side functions available to the Tera-Fy client library
+Type: [Object][66]
 
-<a name="User"></a>
+#### Properties
 
-## User
-**Kind**: global class  
-**Properties**
+*   `devMode` **[Boolean][67]** Operate in devMode - i.e. force outer refresh when encountering an existing TeraFy instance
+*   `How` **(`"detect"` | `"parent"` | `"child"`)** to communicate with TERA. 'parent' assumes that the parent of the current document is TERA, 'child' spawns an iFrame and uses TERA there, 'detect' tries parent and fallsback to 'child'
+*   `modeTimeout` **[Number][68]** How long entities have in 'detect' mode to identify themselves
+*   `siteUrl` **[String][69]** The TERA URL to connect to
+*   `restrictOrigin` **[String][69]** URL to restrict communications to
 
-| Name | Type | Description |
-| --- | --- | --- |
-| id | <code>String</code> | Unique identifier of the user |
-| email | <code>String</code> | The email address of the current user |
-| name | <code>String</code> | The provided full name of the user |
-| isSubscribed | <code>Boolean</code> | Whether the active user has a TERA subscription |
+### dom
 
-<a name="new_User_new"></a>
+DOMElements for this TeraFy instance
 
-### new User()
-User / active session within TERA
+Type: [Object][66]
 
-<a name="Project"></a>
+#### Properties
 
-## Project
-**Kind**: global class  
-**Properties**
+*   `el` **DOMElement** The main tera-fy div wrapper
+*   `iframe` **DOMElement** The internal iFrame element
+*   `stylesheet` **DOMElement** The corresponding stylesheet
 
-| Name | Type | Description |
-| --- | --- | --- |
-| id | <code>String</code> | The Unique ID of the project |
-| name | <code>String</code> | The name of the project |
-| created | <code>String</code> | The creation date of the project as an ISO string |
-| isOwner | <code>Boolean</code> | Whether the current session user is the owner of the project |
+### methods
 
-<a name="new_Project_new"></a>
-
-### new Project()
-Project entry within TERA
+List of function stubs mapped here from the server
+This array is forms the reference of `TeraFy.METHOD()` objects to provide locally which will be mapped via `TeraFy.rpc(METHOD, ...args)`
 
-<a name="TeraFyPlugin"></a>
+Type: [Array][70]<[String][69]>
 
-## TeraFyPlugin
-**Kind**: global class  
-<a name="new_TeraFyPlugin_new"></a>
+### plugins
 
-### new TeraFyPlugin()
-Base TeraFy plugin interface
-This is included as a documentation exanple only
+Loaded plugins via Use()
 
-<a name="TeraFyPluginVue"></a>
+Type: [Array][70]\<TeraFyPlugin>
 
-## TeraFyPluginVue
-**Kind**: global class  
-<a name="new_TeraFyPluginVue_new"></a>
+### send
 
-### new TeraFyPluginVue()
-Vue observables plugin
-Provides the `bindProjectState()` function for Vue based projects
-
-This function is expected to be included via the `terafy.use(MODULE, OPTIONS)` syntax rather than directly
-
-<a name="send"></a>
-
-## send(message) ⇒ <code>Promise.&lt;\*&gt;</code>
 Send a message + wait for a response object
 
-**Kind**: global function  
-**Returns**: <code>Promise.&lt;\*&gt;</code> - A promise which resolves when the operation has completed with the remote reply  
+#### Parameters
+
+*   `message` **[Object][66]** Message object to send
 
-| Param | Type | Description |
-| --- | --- | --- |
-| message | <code>Object</code> | Message object to send |
+Returns **[Promise][71]\<any>** A promise which resolves when the operation has completed with the remote reply
 
-<a name="sendRaw"></a>
+### sendRaw
 
-## sendRaw(message)
 Send raw message content to the server
 This function does not return or wait for a reply - use `send()` for that
 
-**Kind**: global function  
+#### Parameters
 
-| Param | Type | Description |
-| --- | --- | --- |
-| message | <code>Object</code> | Message object to send |
+*   `message` **[Object][66]** Message object to send
 
-<a name="rpc"></a>
+### rpc
 
-## rpc(method) ⇒ <code>Promise.&lt;\*&gt;</code>
 Call an RPC function in the server instance
 
-**Kind**: global function  
-**Returns**: <code>Promise.&lt;\*&gt;</code> - The resolved output of the server function  
+#### Parameters
 
-| Param | Type | Description |
-| --- | --- | --- |
-| method | <code>String</code> | The method name to call |
-| [...] | <code>\*</code> | Optional arguments to pass to the function |
+*   `method` **[String][69]** The method name to call
+*   `args` **...any**&#x20;
 
-<a name="acceptMessage"></a>
+Returns **[Promise][71]\<any>** The resolved output of the server function
+
+### acceptMessage
 
-## acceptMessage(Raw)
 Accept an incoming message
 
-**Kind**: global function  
+#### Parameters
 
-| Param | Type | Description |
-| --- | --- | --- |
-| Raw | <code>MessageEvent</code> | message event to process |
+*   `rawMessage` &#x20;
+*   `Raw` **[MessageEvent][72]** message event to process
 
-<a name="toggleDevMode"></a>
+### acceptPostboxes
 
-## toggleDevMode([devModeEnabled]) ⇒ [<code>TeraFy</code>](#TeraFy)
-Set or toggle devMode
+Listening postboxes, these correspond to outgoing message IDs that expect a response
+
+### createProjectStatePatch
+
+Create + transmit a new project state patch base on the current and previous states
+The transmitted patch follows the [JSPatch][73] standard
+This function accepts an entire projectState instance, computes the delta and transmits that to the server for merging
+
+#### Parameters
+
+*   `newState` **[Object][66]** The local projectState to accept
+*   `oldState` **[Object][66]** The previous projectState to examine against
+
+Returns **[Promise][71]** A promise which will resolve when the operation has completed
+
+### applyProjectStatePatchLocal
+
+Client function which accepts a patch from the server and applies it to local project state
+The patch should follow the [JSPatch][73] standard
+This function is expected to be sub-classed by a plugin
 
-**Kind**: global function  
-**Returns**: [<code>TeraFy</code>](#TeraFy) - This chainable terafy instance  
+#### Parameters
 
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| [devModeEnabled] | <code>String</code> \| <code>Boolean</code> | <code>&#x27;toggle&#x27;</code> | Optional boolean to force dev mode |
+*   `patch` **[Array][70]** A JSPatch patch to apply
 
-<a name="init"></a>
+Returns **[Promise][71]** A promise which will resolve when the operation has completed
+
+### init
 
-## init()
 Initalize the TERA client singleton
+This function can only be called once and will return the existing init() worker Promise if its called againt
+
+#### Parameters
+
+*   `options` **[Object][66]?** Additional options to merge into `settings` via `set`
+
+Returns **[Promise][71]<[TeraFy][1]>** An eventual promise which will resovle with this terafy instance
+
+### detectMode
 
-**Kind**: global function  
-<a name="injectMain"></a>
+Populate `settings.mode`
+Try to communicate with a parent frame, if none assume we need to fallback to child mode
+
+Returns **[Promise][71]<[String][69]>** A promise which will resolve with the detected mode to use
+
+### injectComms
 
-## injectMain()
 Find an existing active TERA server OR initalize one
 
-**Kind**: global function  
-<a name="injectStylesheet"></a>
+Returns **[Promise][71]** A promise which will resolve when the loading has completed and we have found a parent TERA instance or initiallized a child
+
+### injectStylesheet
 
-## injectStylesheet()
 Inject a local stylesheet to handle TERA server functionality
 
-**Kind**: global function  
-<a name="injectMethods"></a>
+### injectMethods
 
-## injectMethods()
 Inject all server methods defined in `methods` as local functions wrapped in the `rpc` function
 
-**Kind**: global function  
-<a name="debug"></a>
+### debug
 
-## debug()
 Debugging output function
 This function will only act if `settings.devMode` is truthy
 
-**Kind**: global function  
+#### Parameters
 
-| Param | Type | Description |
-| --- | --- | --- |
-| [msg...] | <code>String</code> | Output to show |
+*   `msg` **...any**&#x20;
+*   `status` **(`"VERBOSE"` | `"INFO"` | `"LOG"` | `"WARN"` | `"ERROR"`)?** Optional prefixing level to mark the message as. 'WARN' and 'ERROR' will always show reguardless of devMode being enabled
 
-<a name="set"></a>
+### set
 
-## set(key, value) ⇒ [<code>TeraFy</code>](#TeraFy)
 Set or merge settings
 This function also routes 'special' keys like `devMode` to their internal handlers
 
-**Kind**: global function  
-**Returns**: [<code>TeraFy</code>](#TeraFy) - This chainable terafy instance  
+#### Parameters
 
-| Param | Type | Description |
-| --- | --- | --- |
-| key | <code>String</code> \| <code>Object</code> | Either a single setting key to set or an object to merge |
-| value | <code>\*</code> | The value to set if `key` is a string |
+*   `key` **([String][69] | [Object][66])** Either a single setting key to set or an object to merge
+*   `value` **any** The value to set if `key` is a string
 
-<a name="use"></a>
+Returns **[TeraFy][1]** This chainable terafy instance
 
-## use(The, [options]) ⇒ [<code>TeraFy</code>](#TeraFy)
-Include a TeraFy client plugin
+### use
 
-**Kind**: global function  
-**Returns**: [<code>TeraFy</code>](#TeraFy) - This chainable terafy instance  
-
-| Param | Type | Description |
-| --- | --- | --- |
-| The | <code>Object</code> | module function to include. Invoked as `(teraClient:TeraFy, options:Object)` |
-| [options] | <code>Object</code> | Additional options to mutate behaviour |
-
-<a name="toggleFocus"></a>
-
-## toggleFocus([isFocused]) ⇒ [<code>TeraFy</code>](#TeraFy)
-Fit the nested TERA server to a full-screen
-This is usually because the server component wants to perform some user activity like calling $prompt
-
-**Kind**: global function  
-**Returns**: [<code>TeraFy</code>](#TeraFy) - This chainable terafy instance  
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| [isFocused] | <code>String</code> \| <code>Boolean</code> | <code>&#x27;toggle&#x27;</code> | Whether to fullscreen the embedded component |
+Include a TeraFy client plugin
 
-<a name="createContext"></a>
+#### Parameters
 
-## createContext(e) ⇒ <code>Object</code>
-Create a context based on a shallow copy of this instance + additional functionality for the incoming MessageEvent
-This is used by acceptMessage to provide a means to reply / send messages to the originator
+*   `mod` &#x20;
+*   `options` **[Object][66]?** Additional options to mutate behaviour
+*   `The` **[Object][66]** module function to include. Invoked as `(teraClient:TeraFy, options:Object)`
 
-**Kind**: global function  
-**Returns**: <code>Object</code> - A context, which is this instance extended with additional properties  
+Returns **[TeraFy][1]** This chainable terafy instance
 
-| Param | Type | Description |
-| --- | --- | --- |
-| e | <code>MessageEvent</code> | Original message event to base the new context on |
+### mixin
 
-<a name="senderRpc"></a>
+Internal function used by use() to merge an external declared singleton against this object
 
-## senderRpc(method) ⇒ <code>Promise.&lt;\*&gt;</code>
-Request an RPC call from the original sender of a mesasge
-This function only works if the context was sub-classed via `createContext()`
+#### Parameters
 
-**Kind**: global function  
-**Returns**: <code>Promise.&lt;\*&gt;</code> - The resolved output of the server function  
+*   `target` **[Object][66]** Initalied class instance to extend
+*   `source` **[Object][66]** Initalized source object to extend from
 
-| Param | Type | Description |
-| --- | --- | --- |
-| method | <code>String</code> | The method name to call |
-| [...] | <code>\*</code> | Optional arguments to pass to the function |
+### toggleDevMode
 
-<a name="handshake"></a>
+Set or toggle devMode
 
-## handshake() ⇒ <code>Promise.&lt;Object&gt;</code>
-Return basic server information as a form of validation
+#### Parameters
 
-**Kind**: global function  
-**Returns**: <code>Promise.&lt;Object&gt;</code> - Basic promise result  
-**Properties**
+*   `devModeEnabled` **([String][69] | [Boolean][67])** Optional boolean to force dev mode (optional, default `'toggle'`)
 
-| Name | Type | Description |
-| --- | --- | --- |
-| date | <code>Date</code> | Server date |
+Returns **[TeraFy][1]** This chainable terafy instance
 
-<a name="send"></a>
+### toggleFocus
 
-## send(message) ⇒ <code>Promise.&lt;\*&gt;</code>
-Send a message + wait for a response object
+Fit the nested TERA server to a full-screen
+This is usually because the server component wants to perform some user activity like calling $prompt
 
-**Kind**: global function  
-**Returns**: <code>Promise.&lt;\*&gt;</code> - A promise which resolves when the operation has completed with the remote reply  
+#### Parameters
 
-| Param | Type | Description |
-| --- | --- | --- |
-| message | <code>Object</code> | Message object to send |
+*   `isFocused` **([String][69] | [Boolean][67])** Whether to fullscreen the embedded component (optional, default `'toggle'`)
 
-<a name="sendRaw"></a>
+## handshake
 
-## sendRaw(message)
-Send raw message content to the client
+Return basic server information as a form of validation
 
-**Kind**: global function  
+### Properties
 
-| Param | Type | Description |
-| --- | --- | --- |
-| message | <code>Object</code> | Message object to send |
+*   `date` **[Date][74]** Server date
 
-<a name="acceptMessage"></a>
+Returns **[Promise][71]<[Object][66]>** Basic promise result
 
-## acceptMessage(Raw)
-Accept a message from the parent event listener
+## User
 
-**Kind**: global function  
+User / active session within TERA
 
-| Param | Type | Description |
-| --- | --- | --- |
-| Raw | <code>MessageEvent</code> | message event to process |
+### Properties
 
-<a name="requestFocus"></a>
+*   `id` **[String][69]** Unique identifier of the user
+*   `email` **[String][69]** The email address of the current user
+*   `name` **[String][69]** The provided full name of the user
+*   `isSubscribed` **[Boolean][67]** Whether the active user has a TERA subscription
 
-## requestFocus(cb) ⇒ <code>Promise.&lt;\*&gt;</code>
-Wrapper function which runs a callback after the frontend UI has obtained focus
-This is to fix the issue where the front-end needs to switch between a regular webpage and a focused TERA iFrame wrapper
-Any use of $prompt or other UI calls should be wrapped here
+## getUser
 
-**Kind**: global function  
-**Returns**: <code>Promise.&lt;\*&gt;</code> - A promise which resolves with the resulting inner callback payload  
+Fetch the current session user
 
-| Param | Type | Description |
-| --- | --- | --- |
-| cb | <code>function</code> | Async function to run in focused mode |
+Returns **[Promise][71]<[User][41]>** The current logged in user or null if none
 
-<a name="getUser"></a>
+## Project
 
-## getUser() ⇒ [<code>Promise.&lt;User&gt;</code>](#User)
-Fetch the current session user
+Project entry within TERA
 
-**Kind**: global function  
-**Returns**: [<code>Promise.&lt;User&gt;</code>](#User) - The current logged in user or null if none  
-<a name="getProject"></a>
+## getProject
 
-## getProject() ⇒ <code>Promise.&lt;(Project\|null)&gt;</code>
 Get the currently active project, if any
 
-**Kind**: global function  
-**Returns**: <code>Promise.&lt;(Project\|null)&gt;</code> - The currently active project, if any  
-<a name="getProjects"></a>
+Returns **[Promise][71]<([Project][44] | null)>** The currently active project, if any
+
+## getProjects
 
-## getProjects() ⇒ <code>Promise.&lt;Array.&lt;Project&gt;&gt;</code>
 Get a list of projects the current session user has access to
 
-**Kind**: global function  
-**Returns**: <code>Promise.&lt;Array.&lt;Project&gt;&gt;</code> - Collection of projects the user has access to  
-<a name="setActiveProject"></a>
+Returns **[Promise][71]<[Array][70]<[Project][44]>>** Collection of projects the user has access to
+
+## setActiveProject
 
-## setActiveProject(project)
 Set the currently active project within TERA
 
-**Kind**: global function  
+### Parameters
 
-| Param | Type | Description |
-| --- | --- | --- |
-| project | <code>Object</code> \| <code>String</code> | The project to set as active - either the full Project object or its ID |
+*   `project` **([Object][66] | [String][69])** The project to set as active - either the full Project object or its ID
 
-<a name="requireProject"></a>
+## requireProject
 
-## requireProject([options]) ⇒ [<code>Promise.&lt;Project&gt;</code>](#Project)
 Ask the user to select a project from those available - if one isn't already active
 Note that this function will percist in asking the uesr even if they try to cancel
 
-**Kind**: global function  
-**Returns**: [<code>Promise.&lt;Project&gt;</code>](#Project) - The active project  
+### Parameters
 
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| [options] | <code>Object</code> |  | Additional options to mutate behaviour |
-| [options.autoSetActiveProject] | <code>Boolean</code> | <code>true</code> | After selecting a project set that project as active in TERA |
-| [options.title] | <code>String</code> | <code>&quot;Select a project to work with&quot;</code> | The title of the dialog to display |
-| [options.noSelectTitle] | <code>String</code> | <code>&#x27;Select project&#x27;</code> | Dialog title when warning the user they need to select something |
-| [options.noSelectBody] | <code>String</code> | <code>&#x27;A project needs to be selected to continue&#x27;</code> | Dialog body when warning the user they need to select something |
+*   `options` **[Object][66]?** Additional options to mutate behaviour
 
-<a name="selectProject"></a>
+    *   `options.autoSetActiveProject` **[Boolean][67]** After selecting a project set that project as active in TERA (optional, default `true`)
+    *   `options.title` **[String][69]** The title of the dialog to display (optional, default `"Select a project to work with"`)
+    *   `options.noSelectTitle` **[String][69]** Dialog title when warning the user they need to select something (optional, default `'Select project'`)
+    *   `options.noSelectBody` **[String][69]** Dialog body when warning the user they need to select something (optional, default `'A project needs to be selected to continue'`)
+
+Returns **[Promise][71]<[Project][44]>** The active project
+
+## selectProject
 
-## selectProject([options]) ⇒ [<code>Promise.&lt;Project&gt;</code>](#Project)
 Prompt the user to select a project from those available
 
-**Kind**: global function  
-**Returns**: [<code>Promise.&lt;Project&gt;</code>](#Project) - The active project  
+### Parameters
+
+*   `options` **[Object][66]?** Additional options to mutate behaviour
+
+    *   `options.title` **[String][69]** The title of the dialog to display (optional, default `"Select a project to work with"`)
+    *   `options.allowCancel` **[Boolean][67]** Advertise cancelling the operation, the dialog can still be cancelled by closing it (optional, default `true`)
+    *   `options.setActive` **[Boolean][67]** Also set the project as active when selected (optional, default `false`)
 
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| [options] | <code>Object</code> |  | Additional options to mutate behaviour |
-| [options.title] | <code>String</code> | <code>&quot;Select a project to work with&quot;</code> | The title of the dialog to display |
-| [options.allowCancel] | <code>Boolean</code> | <code>true</code> | Advertise cancelling the operation, the dialog can still be cancelled by closing it |
+Returns **[Promise][71]<[Project][44]>** The active project
 
-<a name="getProjectState"></a>
+## getProjectState
 
-## getProjectState([options], Paths) ⇒ <code>Promise.&lt;Object&gt;</code>
 Return the current, full snapshot state of the active project
 
-**Kind**: global function  
-**Returns**: <code>Promise.&lt;Object&gt;</code> - The current project state snapshot  
+### Parameters
 
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| [options] | <code>Object</code> |  | Additional options to mutate behaviour |
-| [options.autoRequire] | <code>Boolean</code> | <code>true</code> | Run `requireProject()` automatically before continuing |
-| Paths | <code>Array.&lt;String&gt;</code> |  | to subscribe to e.g. ['/users/'], |
+*   `options` **[Object][66]?** Additional options to mutate behaviour
 
-<a name="applyProjectStatePatch"></a>
+    *   `options.autoRequire` **[Boolean][67]** Run `requireProject()` automatically before continuing (optional, default `true`)
+*   `Paths` **[Array][70]<[String][69]>** to subscribe to e.g. \['/users/'],
+
+Returns **[Promise][71]<[Object][66]>** The current project state snapshot
+
+## applyProjectStatePatch
 
-## applyProjectStatePatch()
 Apply a computed `just-diff` patch to the current project state
 
-**Kind**: global function  
-<a name="getProjectLibrary"></a>
+### Parameters
+
+*   `Patch` **[Object][66]** to apply
+
+Returns **[Promise][71]** A promise which resolves when the operation has completed
+
+## subscribeProjectState
+
+Subscribe to project state changes
+This will dispatch an RPC call to the source object `applyProjectStatePatchLocal()` function with the patch
+If the above call fails the subscriber is assumed as dead and unsubscribed from the polling list
+
+Returns **[Promise][71]<[Function][75]>** A promise which resolves when a subscription has been created, call the resulting function to unsubscribe
+
+## ProjectFile
+
+Data structure for a project file
+
+### Properties
+
+*   `id` **[String][69]** A UUID string representing the unique ID of the file
+*   `name` **[String][69]** Relative name path (can contain prefix directories) for the human readable file name
+*   `parsedName` **[Object][66]** An object representing meta file parts of a file name
+
+    *   `parsedName.basename` **[String][69]** The filename + extention (i.e. everything without directory name)
+    *   `parsedName.filename` **[String][69]** The file portion of the name (basename without the extension)
+    *   `parsedName.ext` **[String][69]** The extension portion of the name (always lower case)
+    *   `parsedName.dirName` **[String][69]** The directory path portion of the name
+*   `created` **[Date][74]** A date representing when the file was created
+*   `modified` **[Date][74]** A date representing when the file was created
+*   `accessed` **[Date][74]** A date representing when the file was last accessed
+*   `size` **[Number][68]** Size, in bytes, of the file
+*   `mime` **[String][69]** The associated mime type for the file
+
+## getProjectFiles
+
+Fetch the files associated with a given project
+
+### Parameters
+
+*   `options` **[Object][66]** Options which mutate behaviour
+
+    *   `options.autoRequire` **[Boolean][67]** Run `requireProject()` automatically before continuing (optional, default `true`)
+    *   `options.meta` **[Boolean][67]** Pull meta information for each file entity (optional, default `true`)
+
+Returns **[Promise][71]<[ProjectFile][58]>** A collection of project files for the given project
+
+## getProjectLibrary
 
-## getProjectLibrary([options]) ⇒ <code>Promise.&lt;Array.&lt;RefLibRef&gt;&gt;</code>
 Fetch the active projects citation library
 
-**Kind**: global function  
-**Returns**: <code>Promise.&lt;Array.&lt;RefLibRef&gt;&gt;</code> - Collection of references for the selected library  
+### Parameters
+
+*   `path` **[String][69]?** Optional file path to use, if omitted the contents of `options` are used to guess at a suitable file
+*   `options` **[Object][66]?** Additional options to mutate behaviour
 
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| [options] | <code>Object</code> |  | Additional options to mutate behaviour |
-| [options.autoRequire] | <code>Boolean</code> | <code>true</code> | Run `requireProject()` automatically before continuing |
-| [options.multiple] | <code>Boolean</code> | <code>false</code> | Allow selection of multiple libraries |
-| [options.hint] | <code>String</code> \| <code>Array.&lt;String&gt;</code> |  | Hints to identify the library to select in array order of preference. Generally corresponds to the previous stage - e.g. 'deduped', 'review1', 'review2', 'dedisputed' |
+    *   `options.autoRequire` **[Boolean][67]** Run `requireProject()` automatically before continuing (optional, default `true`)
+    *   `options.multiple` **[Boolean][67]** Allow selection of multiple libraries (optional, default `false`)
+    *   `options.filter` **[Function][75]?** Optional async file filter, called each time as `(File:ProjectFile)`
+    *   `options.find` **[Function][75]?** Optional async final stage file filter to reduce all candidates down to one subject file
+    *   `options.hint` **([String][69] | [Array][70]<[String][69]>)?** Hints to identify the library to select in array order of preference. Generally corresponds to the previous stage - e.g. 'deduped', 'review1', 'review2', 'dedisputed'
 
-<a name="setProjectLibrary"></a>
+Returns **[Promise][71]<[Array][70]<[ProjectFile][58]>>** Collection of references for the selected library matching the given hint + filter, this could be a zero length array
+
+## setProjectLibrary
 
-## setProjectLibrary(Collection, [options]) ⇒ <code>Promise</code>
 Save back a projects citation library
 
-**Kind**: global function  
-**Returns**: <code>Promise</code> - A promise which resolves when the save operation has completed  
+### Parameters
 
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| Collection | <code>Array.&lt;RefLibRef&gt;</code> |  | of references for the selected library |
-| [options] | <code>Object</code> |  | Additional options to mutate behaviour |
-| [options.autoRequire] | <code>Boolean</code> | <code>true</code> | Run `requireProject()` automatically before continuing |
-| [options.hint] | <code>String</code> |  | Hint to store against the library. Generally corresponds to the current operation being performed - e.g. 'deduped' |
+*   `Collection` **[Array][70]\<RefLibRef>** of references for the selected library
+*   `options` **[Object][66]?** Additional options to mutate behaviour
 
-<a name="init"></a>
+    *   `options.autoRequire` **[Boolean][67]** Run `requireProject()` automatically before continuing (optional, default `true`)
+    *   `options.hint` **[String][69]?** Hint to store against the library. Generally corresponds to the current operation being performed - e.g. 'deduped'
 
-## init()
-Initialize the browser listener
+Returns **[Promise][71]** A promise which resolves when the save operation has completed
 
-**Kind**: global function  
-<a name="debug"></a>
+[1]: #terafy
 
-## debug()
-Debugging output function
-This function will only act if `settings.devMode` is truthy
+[2]: #settings
+
+[3]: #properties
+
+[4]: #dom
+
+[5]: #properties-1
+
+[6]: #methods
+
+[7]: #plugins
+
+[8]: #send
+
+[9]: #parameters
+
+[10]: #sendraw
+
+[11]: #parameters-1
+
+[12]: #rpc
+
+[13]: #parameters-2
+
+[14]: #acceptmessage
+
+[15]: #parameters-3
+
+[16]: #acceptpostboxes
+
+[17]: #createprojectstatepatch
+
+[18]: #parameters-4
+
+[19]: #applyprojectstatepatchlocal
+
+[20]: #parameters-5
+
+[21]: #init
+
+[22]: #parameters-6
+
+[23]: #detectmode
+
+[24]: #injectcomms
+
+[25]: #injectstylesheet
+
+[26]: #injectmethods
+
+[27]: #debug
+
+[28]: #parameters-7
+
+[29]: #set
+
+[30]: #parameters-8
+
+[31]: #use
+
+[32]: #parameters-9
+
+[33]: #mixin
+
+[34]: #parameters-10
+
+[35]: #toggledevmode
+
+[36]: #parameters-11
+
+[37]: #togglefocus
+
+[38]: #parameters-12
+
+[39]: #handshake
+
+[40]: #properties-2
+
+[41]: #user
+
+[42]: #properties-3
+
+[43]: #getuser
+
+[44]: #project
+
+[45]: #getproject
+
+[46]: #getprojects
+
+[47]: #setactiveproject
+
+[48]: #parameters-13
+
+[49]: #requireproject
+
+[50]: #parameters-14
+
+[51]: #selectproject
+
+[52]: #parameters-15
+
+[53]: #getprojectstate
+
+[54]: #parameters-16
+
+[55]: #applyprojectstatepatch
+
+[56]: #parameters-17
+
+[57]: #subscribeprojectstate
+
+[58]: #projectfile
+
+[59]: #properties-4
+
+[60]: #getprojectfiles
+
+[61]: #parameters-18
+
+[62]: #getprojectlibrary
+
+[63]: #parameters-19
+
+[64]: #setprojectlibrary
+
+[65]: #parameters-20
+
+[66]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
-**Kind**: global function  
+[67]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
 
-| Param | Type | Description |
-| --- | --- | --- |
-| [msg...] | <code>String</code> | Output to show |
+[68]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
 
-<a name="init"></a>
+[69]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
 
-## init()
-Optional function to be included when the main TeraFyClient is initalized
+[70]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
 
-**Kind**: global function  
-<a name="bindProjectState"></a>
+[71]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
 
-## bindProjectState([options], Paths) ⇒ <code>Promies.&lt;Reactive.&lt;Object&gt;&gt;</code>
-Return a Vue reactive object that can be read/written which whose changes will transparently be written back to the TERA server instance
+[72]: https://developer.mozilla.org/docs/Web/API/MessageEvent
 
-**Kind**: global function  
-**Returns**: <code>Promies.&lt;Reactive.&lt;Object&gt;&gt;</code> - A reactive object representing the project state  
+[73]: http://jsonpatch.com
 
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| [options] | <code>Object</code> |  | Additional options to mutate behaviour |
-| [options.autoRequire] | <code>Boolean</code> | <code>true</code> | Run `requireProject()` automatically before continuing |
-| [options.write] | <code>Boolean</code> | <code>true</code> | Allow local reactivity to writes - send these to the server |
-| Paths | <code>Array.&lt;String&gt;</code> |  | to subscribe to e.g. ['/users/'], |
+[74]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date
 
+[75]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function