docloop

Class: DocloopAdapter

docloop DocloopAdapter

This Class and any Class that extends DocloopAdapter are supposed to be passed to DocloopCore.use().

All methods that start with an underscore '_' expect the actual session to be passed as argument and will usually have a counterpart without the leading underscore that expects the adapter's session data as argument instead.

The preferred way for an adapter to communicate with the core system or other adapters is through events. See module:docloop.DocloopCore#relayEvent.

Tutorial: Custom adapters

new DocloopAdapter(core, config)

Parameters:
Name Type Description
core DocloopCore

An instance of the docloop core.
config Object
Properties
Name Type Argument Default Description
id String

The id this adapter should be identified by (e.g. 'github').
extraId String <optional>

This maybe useful if a custom adapter has a fixed id, but is supposed to be instantiated twice with different configs.
name String <optional>
 'DocloopAdapter'

A pretty name for the Adapter, that can actually be used in a client.
type String

Either 'source' or 'target'.
endPointClass EndpointClass <optional>
 DocloopEndpoint

Endpoint class or any class extending Endpoint.
extraEndpoints boolean <optional>
 false

True iff there are valid endpoints that are not returned by .getEndpoints()
endpointDefaultConfig Object <optional>
 {}

Configuration object with default values for endpoints. These values will be used if no other values are provided when a new enpoint is created.
extraEndpoints boolean

true iff there are valid endpoints that are not returned by .getEndpoints()
Properties:
Name Type Argument Description
core DocloopCore
id String
name String
type String
endPointClass DocloopEndpoint
endpointDefaultConfig Object
app ExpressApp

Express sub app of core.app. All routes will be relative to '/adapters/'+this.id.
endpoints Collection

Mongo-db collection for stored endpoints.
help String <optional>

Help text used by the client.

Extends

  • EventEmitter

Methods

_clearSessionData(session)

Clears the data associated with this adapter in the provided session object. Returns an empty object. Modifying its values will modify the session.

Parameters:
Name Type Description
session Session

Express session
Returns:

Empty session data

Type
SessionData

<async> _getAuthState(session)

Calls .getAuthState() with sessionData.

Parameters:
Name Type Description
session Session

Express session
Returns:
Type
AuthState

<async> _getData(session)

Collects adapter data for client use.

Parameters:
Name Type Description
session Session

Express session
Returns:
Type
AdapterData

<async> _getEndpoints(session)

Calls .getEndpoints() with sessionData.

Parameters:
Name Type Description
session Session

Express session
Returns:
Type
Array.<DocloopEndpoint>

_getSessionData(session)

Extracts the data associated with this adapter in the provided session object. Modifying its values will modify the session.

Parameters:
Name Type Description
session Session

Express session
Returns:

Adapter's session data

Type
SessionData

<async> _getStoredEndpoint(id, session)

Calls .getStoredEndpoint() with sessionData.

Parameters:
Name Type Description
id String | bson
session Session

Express session
Returns:
Type
ValidEndpoint

<async> _getStoredEndpoints(session)

Calls .getStoredEndpoints with sessionData.

Parameters:
Name Type Description
session Session

Express session
Returns:
Type
Array.<DocloopEndpoint>

<async, route> _handleGetEndpointsRequest(req, res)

Route:
MethodPath
GET /adapters/:adapter-id/endpoints

Express request handler. Sends privileged Enpoints to the client.

Parameters:
Name Type Description
req Object

Express request object
res Object

Express result object

<async, route> _handleGetGuessEndpointRequest(req, res)

Route:
MethodPath
GET /adapters/:adapter-id/guessEndpoint/:str

Express request handler. Guesses Endpoint from request paramter and sends it to the client.

Parameters:
Name Type Description
req Object

Express request object

Properties
Name Type Description
params Object

Request parameters

Properties
Name Type Description
str String

String to guess the endpoint from
res Object

Express result object

<async, route> _handleGetRequest(req, res)

Route:
MethodPath
GET /adapters/:adapter-id

Express request handler. Sends AdapterData to the client.

Parameters:
Name Type Description
req Object

Express request object
res Object

Express result object

<async, route> _handlePostSignOff()

Route:
MethodPath
GET /adapters/:adapter-id/signoff

Express request handler. Clears current session data for this adapter.

<async, abstract> getAuthState(session_data)

This method is meant to be overwritten by a custom adapter class. Returns the authorization state for the adapter in the current session.

Parameters:
Name Type Description
session_data SessionData

Data of the current session associated with this adapter
Returns:
Type
AuthState

<async, abstract> getEndpoints(session_data)

This method is meant to be overwritten by a custom adapter class. Returns valid endpoints the current session has privileged access to.

Parameters:
Name Type Description
session_data SessionData

Data of the current session associated with this adapter
Returns:
Type
Array.<ValidEndpoint>

<async> getStoredEndpoint(id)

Returns the endpoint with the provided id. Throws an error if it cannot be found or the session lacks privileges to access it.

Parameters:
Name Type Description
id String | bson

Mongo-db id
Throws:

  • If the endpoint cannot be found.

    Type
    DocloopError

  • If the endpoint cannot be validated for the session.

    Type
    DocloopError
Returns:
Type
Endpoint

<async, abstract> getStoredEndpoints(session_data)

This method is meant to be overwritten by a custom adapter class. Retuns all endpoints stored in the db, that are also valid for the current session.

Parameters:
Name Type Description
session_data SessionData

Data of the current session associated with this adapter
Returns:
Type
Array.<ValidEndpoint>

newEndpoint(data)

Creates a new instance of the endpoint class associated with this adapter. The new endpoint's adapter will be set to this adapter.

Parameters:
Name Type Description
data Object

Data to instantiate the endpoint with.
Returns:

Endpoint

Type
DocloopEndpoint

Type Definitions

Adapter

An instance of either DocloopAdapter or any Class extending it.

Type:
  • Object

AdapterClass

Either DocloopAdapter or any Class extending it.

Type:
  • Class

AdapterData

Data concerning an adapter meant for client use.

Type:
  • Object
Properties:
Name Type Description
id String

The adapter's id
name String

The adapter's name
type String

The adapter's type
extraEndpoints boolean

The adapter's .extraEndpoints value
endpointDefaultConfig Object

The adapter's .endpointDefaultConfig'value
auth AuthState

The adapters authorization state. (see ...)

Annotation

TODO

AuthState

Authorization data for client use. A truthy user value indicated that the session user is logged in with a third party service.

Type:
  • Object
Properties:
Name Type Argument Default Description
user String <optional>
 null

The username, login or id of the service the adapter makes use of
link String <optional>
 null

Authorization Url. This is the url the client is supposed to open in order to login with the service this adapters want to make use of. Make sure to also add a route to the adapters sub app in order to catch the callback or webhook or wahever your service calls after the authorization.

SessionData

Every adapter has its own reserved part of the express session object to store data in. SessionData refers to that part. Modifying SessionData will modify the session. Whenever SessionData is mentioned, it is assumed that there is an adapter it belongs to. If you come across the real express session object you can access the adapter's reserved session part by calling DocloopAdapter#getSessionData. The core and the base classes for adapters, links and endpoints use wrappers for some of the member methods to replace the original express session object with the adapters SessionData, in order to separate the data each adapter has access to. Wrapped methods are prefixed with an underscore _.

Type:
  • Object

Events

annotation

TODO

Type: Annotation