1 | [![Communibase](https://www.communibase.nl/img/siteLogo.png)](https://www.communibase.nl)
|
2 |
|
3 | [![Known Vulnerabilities](https://snyk.io/test/github/kingsquare/communibase-connector-js/badge.svg)](https://snyk.io/test/github/kingsquare/communibase-connector-js)
|
4 |
|
5 | A general-purpose Communibase client for node.js projects. It is primarily a Singleton connector doing REST-calls on the Communibase API using a queuing system. It returns [A+ promises](https://github.com/promises-aplus/promises-spec) for Communibase responses. Behaviour is reflected by a PHP-version that can be found at [Github](https://github.com/kingsquare/communibase-connector-js).
|
6 |
|
7 | Installation
|
8 | ============
|
9 |
|
10 | ```
|
11 | npm install --save communibase-connector-js
|
12 | ```
|
13 |
|
14 | Usage
|
15 | =====
|
16 |
|
17 | Make sure environment variable exists with your API-key called COMMUNIBASE_KEY
|
18 |
|
19 | ```js
|
20 | const { Connector } = require('communibase-connector-js');
|
21 |
|
22 | const cbc = new Connector(process.env.COMMUNIBASE_KEY);
|
23 |
|
24 | cbc.search('Person', { firstName: 'Tim' }).then((peopleCalledTim) => {
|
25 | // eslint-disable-next-line no-console
|
26 | console.log(peopleCalledTim.length);
|
27 | });
|
28 | ```
|
29 |
|
30 | Advanced usage
|
31 | --
|
32 |
|
33 | If you need to connect to a specific version of the endpoint, you may want to set a environment variable ```COMMUNIBASE_API_URL``` e.g.
|
34 |
|
35 | ```js
|
36 | COMMUNIBASE_API_URL=https://api.communibase.nl/0.1/
|
37 | ```
|
38 |
|
39 | ### Use via a tunnel requires also adding an extra Host header
|
40 |
|
41 | ```bash
|
42 | COMMUNIBASE_API_URL=https://17.42.0.1:8888/0.1/ COMMUNIBASE_API_HOST=api.communibase.nl node script.js
|
43 | ```
|
44 |
|
45 | API
|
46 | --
|
47 |
|
48 | The following methods exists, all returning a [promise](https://github.com/petkaantonov/bluebird/blob/master/API.md#new-promisefunctionfunction-resolve-function-reject-resolver--promise) for a result.
|
49 |
|
50 | "selectors" may be provided [MongoDb style](http://docs.mongodb.org/manual/reference/method/db.collection.find/#db.collection.find).
|
51 |
|
52 | "params" is a key value store for e.g. fields, limit, page and/or sort . See [API docs](https://api.communibase.nl/docs/) for more details.
|
53 |
|
54 | The param ```includeMetadata``` will set a metadata-property on the promise, when available.
|
55 |
|
56 | ```js
|
57 | cbc.getById(entityType, id, params): Promise for Entity;
|
58 |
|
59 | cbc.getByIds(entityType, id[], params): Promise for Entity[];
|
60 |
|
61 | cbc.getAll(entityType, params): Promise for Entity[];
|
62 |
|
63 | cbc.getId(entityType, selector): Promise for id[];
|
64 |
|
65 | cbc.getIds(entityType, selector, params): Promise for id[];
|
66 |
|
67 | cbc.search(entityType, selector, params): Promise for Entity[];
|
68 |
|
69 | cbc.update(entityType, document): Promise for Entity;
|
70 |
|
71 | cbc.destroy(entityType, id): Promise for null;
|
72 |
|
73 | cbc.undelete(entityType, id): Promise for null;
|
74 | ```
|
75 |
|
76 | Entity
|
77 | --
|
78 | An entity is an plain JavaScript object: a key/value store of data in Communibase, also called "document".
|
79 |
|
80 | E.g.
|
81 |
|
82 | ```js
|
83 | {
|
84 | "firstName": "Tim",
|
85 | "addresses": [
|
86 | {
|
87 | "street": "Breestraat"
|
88 | }
|
89 | ]
|
90 | }
|
91 |
|
92 | ```
|
93 |
|
94 | Error handling
|
95 | --
|
96 |
|
97 | The ```update```-Promise may be rejected if an entity is not considered valid. The Error has one or more of the following properties:
|
98 |
|
99 | ```js
|
100 | {
|
101 | "message": <a simplified error-string>
|
102 | "code": <http response code of API>
|
103 | "errors": {
|
104 | [
|
105 | "field": "<string>",
|
106 | "message": "<string>"
|
107 | ], ...
|
108 | }
|
109 | }
|
110 | ```
|
111 |
|
112 | File handling
|
113 | --
|
114 |
|
115 | upload a new file or update an existing one:
|
116 |
|
117 | ```js
|
118 | /**
|
119 | * @param {Stream|Buffer|String} resource a stream, buffer or a content-string
|
120 | * @param {String} name The binary name (i.e. a filename)
|
121 | * @param {String} destinationPath The "directory location"
|
122 | * @param {String} id The `File` id to replace the contents of (optional; if not set then creates a new File)
|
123 | */
|
124 |
|
125 | cbc.updateBinary = function updateBinary(resource, name, destinationPath, id) {
|
126 | ```
|
127 |
|
128 | create a readable stream:
|
129 |
|
130 | ```js
|
131 | cbc.createReadStream(fileId) : Stream;
|
132 | ```
|
133 |
|
134 | Work with document history
|
135 | --
|
136 |
|
137 | First, find the _id of both the document and the version you are looking for. To find all available versions of a specific document, use
|
138 |
|
139 | ```js
|
140 | cbc.getHistory(entityType, id) : Promise for VersionInformation[];
|
141 | ```
|
142 |
|
143 | Alternatively, you can search the entire history of documents to look for specific properties. e.g.
|
144 |
|
145 | ```js
|
146 | //Lookup all versions of any person (even deleted documents) ever with first name Tim.
|
147 |
|
148 | cbc.historySearch('Person', { firstName: 'Tim' }): Promise for VersionInformation[]
|
149 | ```
|
150 |
|
151 | VersionInformation has the following structure
|
152 | * _id - The _id of the version.
|
153 | * refId - The _id of the original document. You can use this at the regular CRUD endpoint
|
154 | * updatedAt - The date this version was created
|
155 | * updatedBy - A human readable description describing who created it
|
156 |
|
157 | With an _id and a refId, we can lookup that specific version via the API
|
158 |
|
159 | ```js
|
160 | cbc.getById(entityType, id, params, versionId) : Promise for version of document;
|
161 | ```
|
162 |
|
163 | Aggregate document data via Mongodb pipeline. For more information, see
|
164 | [http://docs.mongodb.org/manual/core/aggregation-pipeline/](http://docs.mongodb.org/manual/core/aggregation-pipeline/)
|
165 |
|
166 | ```js
|
167 | cbc.aggregate(entityType, aggregationPipeline);
|
168 |
|
169 | //Example:
|
170 | var participantCounters = cbc.aggregate('Event', [
|
171 | { "$match": { "_id": {"$ObjectId": "52f8fb85fae15e6d0806e7c7"} } },
|
172 | { "$unwind": "$participants" },
|
173 | { "$group": { "_id": "$_id", "participantCount": { "$sum": 1 } } }
|
174 | ]);
|
175 | ```
|
176 |
|
177 | Work with "DocumentReferences"
|
178 | --
|
179 |
|
180 | A DocumentReference is a unified specification to point to some other (sub-)doucment
|
181 | within the administration. A DocumentReference looks like:
|
182 |
|
183 | ```js
|
184 | {
|
185 | rootDocumentId: '524aca8947bd91000600000c',
|
186 | rootDocumentEntityType: 'Person',
|
187 | path: [
|
188 | {
|
189 | field: 'addresses',
|
190 | objectId: '53440792463cda7161000003'
|
191 | }, ...
|
192 | ]
|
193 | }
|
194 | ```
|
195 |
|
196 | The contents will be parsed and the requested data will be retrieved.
|
197 |
|
198 | EXPERIMENTAL - Work with local in-memory cache for query results
|
199 | --
|
200 |
|
201 | The connector may cache documents locally. To enable in-memory cache for a certain instance of the connector:
|
202 |
|
203 | ```js
|
204 | cbc.enableCache(communibaseAdministrationId, socketServiceUrl)
|
205 | ```
|
206 |
|
207 | Contact Kingsquare for these values in your particular scenario and use with caution: BEWARE of excessive memory usage!
|