opengate-js 16.2.0 → 16.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +84 -8
- package/dist/{opengate-api-bower-16.2.0.js → opengate-api-bower-16.3.0.js} +1006 -665
- package/dist/opengate-api-bower-16.3.0.js.map +6 -0
- package/dist/opengate-api-bower-16.3.0.min.js +117 -0
- package/dist/opengate-api-bower-16.3.0.min.js.map +6 -0
- package/dist/opengate-api-npm.js +4 -0
- package/dist/opengate-api-npm.js.map +1 -1
- package/dist/opengate-api-npm.mjs +133 -21
- package/dist/opengate-api-npm.mjs.map +1 -1
- package/dist/src/InternalOpenGateAPI.js +38 -2
- package/dist/src/InternalOpenGateAPI.js.map +1 -1
- package/dist/src/searching/AssetSearch.js +1 -1
- package/dist/src/searching/AssetSearch.js.map +1 -1
- package/dist/src/searching/BaseSearch.js +3 -3
- package/dist/src/searching/DeviceSearch.js +1 -1
- package/dist/src/searching/DeviceSearch.js.map +1 -1
- package/dist/src/searching/EntitySearch.js +1 -1
- package/dist/src/searching/EntitySearch.js.map +1 -1
- package/dist/src/searching/WPSearch.js +1 -1
- package/dist/src/searching/WPSearch.js.map +1 -1
- package/dist/src/util/NorthAmpliaREST.js +77 -2
- package/dist/src/util/NorthAmpliaREST.js.map +1 -1
- package/dist/src/util/http/RequestSpec.js +21 -10
- package/dist/src/util/http/RequestSpec.js.map +1 -1
- package/opengate-api-npm.js +6 -0
- package/package.json +2 -2
- package/src/InternalOpenGateAPI.js +46 -2
- package/src/searching/AssetSearch.js +1 -1
- package/src/searching/BaseSearch.js +3 -3
- package/src/searching/DeviceSearch.js +1 -1
- package/src/searching/EntitySearch.js +1 -1
- package/src/searching/WPSearch.js +1 -1
- package/src/util/NorthAmpliaREST.js +87 -2
- package/src/util/http/RequestSpec.js +29 -10
- package/types/opengate-api-npm.d.ts +7 -1
- package/types/src/InternalOpenGateAPI.d.ts +103 -8
- package/types/src/util/NorthAmpliaREST.d.ts +25 -0
- package/dist/opengate-api-bower-16.2.0.js.map +0 -6
- package/dist/opengate-api-bower-16.2.0.min.js +0 -116
- package/dist/opengate-api-bower-16.2.0.min.js.map +0 -6
package/opengate-api-npm.js
CHANGED
|
@@ -4,7 +4,13 @@ import InternalOpenGateAPI from './src/InternalOpenGateAPI';
|
|
|
4
4
|
import NorthAmpliaREST from './src/util/NorthAmpliaREST';
|
|
5
5
|
import SouthAmpliaREST from './src/util/SouthAmpliaREST';
|
|
6
6
|
|
|
7
|
+
/** @typedef {import('./src/InternalOpenGateAPI').OpenGateOptions} OpenGateOptions */
|
|
8
|
+
|
|
7
9
|
export default class OpenGateAPI extends InternalOpenGateAPI {
|
|
10
|
+
/**
|
|
11
|
+
* @param {import('./src/InternalOpenGateAPI').OpenGateOptions & Record<string, unknown>} _options - the client's
|
|
12
|
+
* configuration; see the README's Configuration section.
|
|
13
|
+
*/
|
|
8
14
|
constructor(_options) {
|
|
9
15
|
super(
|
|
10
16
|
new NorthAmpliaREST(_options, {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "opengate-js",
|
|
3
|
-
"version": "16.
|
|
3
|
+
"version": "16.3.0",
|
|
4
4
|
"description": "JavaScript client for the OpenGate North and South APIs, with a fluent builder API. Runs in Node.js and in the browser.",
|
|
5
5
|
"main": "dist/opengate-api-npm.js",
|
|
6
6
|
"module": "dist/opengate-api-npm.mjs",
|
|
@@ -34,7 +34,7 @@
|
|
|
34
34
|
},
|
|
35
35
|
"homepage": "https://documentation.opengate.es/libs/ogapi-docs/index.html",
|
|
36
36
|
"author": "",
|
|
37
|
-
"license": "
|
|
37
|
+
"license": "Apache-2.0",
|
|
38
38
|
"engines": {
|
|
39
39
|
"node": ">=20.19.0"
|
|
40
40
|
},
|
|
@@ -176,6 +176,26 @@ import DevicePlansFinder from './plan/DevicePlansFinder';
|
|
|
176
176
|
* It stays process-wide, as the patch was: one callback for every client, last registration wins.
|
|
177
177
|
*/
|
|
178
178
|
const registerBeforeStartHook = setBeforeStart;
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* What `new OpenGateAPI(options)` accepts. The README's Configuration section explains each one.
|
|
182
|
+
* @typedef {object} OpenGateOptions
|
|
183
|
+
* @property {string} url - Base URL of the North API.
|
|
184
|
+
* @property {string} [apiKey] - Sent as `X-ApiKey`.
|
|
185
|
+
* @property {string} [jwt] - Sent as `Authorization: Bearer ...`; takes precedence over `apiKey` on North calls.
|
|
186
|
+
* @property {number} [timeout] - Milliseconds. Defaults to 5000; -1 disables the timeout.
|
|
187
|
+
* @property {{url: string}} [south] - Only needed to call the South API.
|
|
188
|
+
* @property {{beforeStart?: function(object): void}} [hooks] - `beforeStart` receives each request just before it leaves.
|
|
189
|
+
* @property {object} [mocks] - Routes answered locally instead of calling OpenGate, keyed by verb and path.
|
|
190
|
+
* @property {boolean|{debug?: Function, info?: Function, warn?: Function, error?: Function}} [logger] - Where the
|
|
191
|
+
* library's own messages go: `false` silences it, `true` reports everything, or your own logger.
|
|
192
|
+
* @property {boolean} [readOnly] - Refuse every request but GET and searches before it is sent.
|
|
193
|
+
* @property {{organization: string, identifier: string, ds: string}} [_internalCountriesFilter] - Required by
|
|
194
|
+
* `newCountriesCatalog()`.
|
|
195
|
+
* @property {string} [port] - Ignored. Kept so code that passes it still type-checks.
|
|
196
|
+
* @property {string} [version] - Ignored. Kept so code that passes it still type-checks.
|
|
197
|
+
*/
|
|
198
|
+
|
|
179
199
|
/**
|
|
180
200
|
* This is an abstract class. It must be extended by another class that defines the backend, and it is used to make
|
|
181
201
|
* requests to the OpenGate North API from a browser or a Node.js server.
|
|
@@ -183,8 +203,9 @@ const registerBeforeStartHook = setBeforeStart;
|
|
|
183
203
|
export default class InternalOpenGateAPI {
|
|
184
204
|
/**
|
|
185
205
|
* Constructor
|
|
186
|
-
* @param {
|
|
187
|
-
* @param {
|
|
206
|
+
* @param {object} northAmpliaREST - the client that sends requests to the North API.
|
|
207
|
+
* @param {object} southAmpliaREST - the client that sends requests to the South API.
|
|
208
|
+
* @param {OpenGateOptions & Record<string, unknown>} _options - the client's configuration.
|
|
188
209
|
*/
|
|
189
210
|
constructor(northAmpliaREST, southAmpliaREST, _options) {
|
|
190
211
|
if (this.constructor === InternalOpenGateAPI) {
|
|
@@ -202,6 +223,8 @@ export default class InternalOpenGateAPI {
|
|
|
202
223
|
if (_options.hooks && _options.hooks.beforeStart && typeof _options.hooks.beforeStart === 'function') {
|
|
203
224
|
registerBeforeStartHook(_options.hooks.beforeStart);
|
|
204
225
|
}
|
|
226
|
+
// Kept as given, for clone(). Frozen so flipping readOnly here cannot widen a clone.
|
|
227
|
+
Object.defineProperty(this, '_options', { value: Object.freeze({ ..._options }) });
|
|
205
228
|
this.Napi = northAmpliaREST;
|
|
206
229
|
this.Sapi = southAmpliaREST;
|
|
207
230
|
this.EX = Expression;
|
|
@@ -211,6 +234,27 @@ export default class InternalOpenGateAPI {
|
|
|
211
234
|
this.entityBuilder = new EntityBuilder(this);
|
|
212
235
|
}
|
|
213
236
|
|
|
237
|
+
/**
|
|
238
|
+
* A new client with this one's options, and the given ones on top. The merge is shallow: an
|
|
239
|
+
* override of `south` replaces the whole object.
|
|
240
|
+
*
|
|
241
|
+
* A clone of a read-only client is read-only too, and asking for `readOnly: false` throws: code
|
|
242
|
+
* handed a read-only client cannot widen it this way. `logger` and `hooks` are process-wide, so
|
|
243
|
+
* overriding them in a clone changes them for every client.
|
|
244
|
+
* @example
|
|
245
|
+
* const widgetApi = ogapi.clone({ readOnly: true });
|
|
246
|
+
* @param {Partial<OpenGateOptions> & Record<string, unknown>} [overrides] - the options to change.
|
|
247
|
+
* @return {this}
|
|
248
|
+
*/
|
|
249
|
+
clone(overrides = {}) {
|
|
250
|
+
if (this._options.readOnly && 'readOnly' in overrides && !overrides.readOnly) {
|
|
251
|
+
throw new Error('OGAPI: a clone of a read-only client is read-only too');
|
|
252
|
+
}
|
|
253
|
+
const options = { ...this._options, ...overrides };
|
|
254
|
+
if (this._options.readOnly) options.readOnly = true;
|
|
255
|
+
return new this.constructor(options);
|
|
256
|
+
}
|
|
257
|
+
|
|
214
258
|
/**
|
|
215
259
|
* This returns a util to find a user
|
|
216
260
|
* @return {UserFinder}
|
|
@@ -31,7 +31,7 @@ export default class AssetSearch extends Search {
|
|
|
31
31
|
var promise = defered.promise;
|
|
32
32
|
var parameters = this._getUrlParameters();
|
|
33
33
|
|
|
34
|
-
this._ogapi.Napi.
|
|
34
|
+
this._ogapi.Napi._searchPost(this._resource, this._filter(), this._timeout, this._getExtraHeaders(), parameters)
|
|
35
35
|
.then(response => {
|
|
36
36
|
let resultQuery = response.body;
|
|
37
37
|
let statusCode = response.statusCode;
|
|
@@ -77,7 +77,7 @@ export default class BaseSearch {
|
|
|
77
77
|
execute() {
|
|
78
78
|
var defered = q.defer();
|
|
79
79
|
var promise = defered.promise;
|
|
80
|
-
this._ogapi.Napi.
|
|
80
|
+
this._ogapi.Napi._searchPost(
|
|
81
81
|
this._resource,
|
|
82
82
|
this._filter(),
|
|
83
83
|
this._timeout,
|
|
@@ -146,7 +146,7 @@ export default class BaseSearch {
|
|
|
146
146
|
Accept: 'text/plain'
|
|
147
147
|
});
|
|
148
148
|
|
|
149
|
-
this._ogapi.Napi.
|
|
149
|
+
this._ogapi.Napi._searchPost(
|
|
150
150
|
this._resource,
|
|
151
151
|
filter,
|
|
152
152
|
this._timeout,
|
|
@@ -205,7 +205,7 @@ export default class BaseSearch {
|
|
|
205
205
|
statusCode: 403
|
|
206
206
|
});
|
|
207
207
|
} else {
|
|
208
|
-
_this._ogapi.Napi.
|
|
208
|
+
_this._ogapi.Napi._searchPost(
|
|
209
209
|
_this._resource,
|
|
210
210
|
filter,
|
|
211
211
|
_this._timeout,
|
|
@@ -28,7 +28,7 @@ export default class DeviceSearch extends Search {
|
|
|
28
28
|
var defered = q.defer();
|
|
29
29
|
var promise = defered.promise;
|
|
30
30
|
var parameters = this._getUrlParameters();
|
|
31
|
-
this._ogapi.Napi.
|
|
31
|
+
this._ogapi.Napi._searchPost(this._resource, this._filter(), this._timeout, this._getExtraHeaders(), parameters)
|
|
32
32
|
.then(response => {
|
|
33
33
|
let resultQuery = response.body;
|
|
34
34
|
let statusCode = response.statusCode;
|
|
@@ -32,7 +32,7 @@ export default class EntitySearch extends Search {
|
|
|
32
32
|
var defered = q.defer();
|
|
33
33
|
var promise = defered.promise;
|
|
34
34
|
var parameters = this._getUrlParameters();
|
|
35
|
-
this._ogapi.Napi.
|
|
35
|
+
this._ogapi.Napi._searchPost(this._resource, this._filter(), this._timeout, this._getExtraHeaders(), parameters)
|
|
36
36
|
.then(response => {
|
|
37
37
|
let resultQuery = response.body;
|
|
38
38
|
let statusCode = response.statusCode;
|
|
@@ -46,7 +46,7 @@ export default class WPSearch extends BaseSearch {
|
|
|
46
46
|
statusCode: 403
|
|
47
47
|
});
|
|
48
48
|
} else {
|
|
49
|
-
_this._ogapi.Napi.
|
|
49
|
+
_this._ogapi.Napi._searchPost(_this._resource, filter, _this._timeout, _this._getExtraHeaders(), _this._getUrlParameters())
|
|
50
50
|
.then(response => {
|
|
51
51
|
let statusCode = response.statusCode;
|
|
52
52
|
let body = response.body;
|
|
@@ -158,6 +158,8 @@ export default class NorthAmpliaREST {
|
|
|
158
158
|
* @return {Promise}
|
|
159
159
|
*/
|
|
160
160
|
get(url, timeout, headers, parameters, asBlob, serviceBaseURL) {
|
|
161
|
+
const rejected = this._guard('GET', url, serviceBaseURL);
|
|
162
|
+
if (rejected) return rejected;
|
|
161
163
|
const _url = this._createUrl(url, parameters, serviceBaseURL);
|
|
162
164
|
logger.info('GET', _url);
|
|
163
165
|
var req = new RequestSpec('GET', _url);
|
|
@@ -175,6 +177,8 @@ export default class NorthAmpliaREST {
|
|
|
175
177
|
* @return {Promise}
|
|
176
178
|
*/
|
|
177
179
|
patch(url, data, timeout, headers, parameters, serviceBaseURL) {
|
|
180
|
+
const rejected = this._guard('PATCH', url, serviceBaseURL);
|
|
181
|
+
if (rejected) return rejected;
|
|
178
182
|
const _url = this._createUrl(url, parameters, serviceBaseURL);
|
|
179
183
|
logger.info('PATCH', _url);
|
|
180
184
|
var req = new RequestSpec('PATCH', _url).send(data);
|
|
@@ -193,6 +197,8 @@ export default class NorthAmpliaREST {
|
|
|
193
197
|
* @return {Promise}
|
|
194
198
|
*/
|
|
195
199
|
post(url, data, timeout, headers, parameters, serviceBaseURL) {
|
|
200
|
+
const rejected = this._guard('POST', url, serviceBaseURL);
|
|
201
|
+
if (rejected) return rejected;
|
|
196
202
|
const _url = this._createUrl(url, parameters, serviceBaseURL);
|
|
197
203
|
logger.info('POST', _url);
|
|
198
204
|
var req = new RequestSpec('POST', _url).send(data);
|
|
@@ -212,6 +218,8 @@ export default class NorthAmpliaREST {
|
|
|
212
218
|
* @return {Promise}
|
|
213
219
|
*/
|
|
214
220
|
post_multipart(url, formData, events, timeout, headers, parameters, serviceBaseURL) {
|
|
221
|
+
const rejected = this._guard('POST', url, serviceBaseURL);
|
|
222
|
+
if (rejected) return rejected;
|
|
215
223
|
const _url = this._createUrl(url, parameters, serviceBaseURL);
|
|
216
224
|
logger.info('POST_MULTIPART', _url);
|
|
217
225
|
let req = new RequestSpec('POST', _url);
|
|
@@ -232,6 +240,8 @@ export default class NorthAmpliaREST {
|
|
|
232
240
|
* @return {Promise}
|
|
233
241
|
*/
|
|
234
242
|
put(url, data, timeout, headers, parameters, serviceBaseURL) {
|
|
243
|
+
const rejected = this._guard('PUT', url, serviceBaseURL);
|
|
244
|
+
if (rejected) return rejected;
|
|
235
245
|
const _url = this._createUrl(url, parameters, serviceBaseURL);
|
|
236
246
|
logger.info('PUT', _url);
|
|
237
247
|
var req = new RequestSpec('PUT', _url).send(data);
|
|
@@ -259,6 +269,8 @@ export default class NorthAmpliaREST {
|
|
|
259
269
|
* @return {Promise}
|
|
260
270
|
*/
|
|
261
271
|
put_multipart(url, formData, events, timeout, headers, parameters, serviceBaseURL) {
|
|
272
|
+
const rejected = this._guard('PUT', url, serviceBaseURL);
|
|
273
|
+
if (rejected) return rejected;
|
|
262
274
|
const _url = this._createUrl(url, parameters, serviceBaseURL);
|
|
263
275
|
logger.info('PUT_MULTIPART', _url);
|
|
264
276
|
let req = new RequestSpec('PUT', _url);
|
|
@@ -341,6 +353,8 @@ export default class NorthAmpliaREST {
|
|
|
341
353
|
* @return {Promise}
|
|
342
354
|
*/
|
|
343
355
|
delete(url, timeout, headers, parameters, body, serviceBaseURL) {
|
|
356
|
+
const rejected = this._guard('DELETE', url, serviceBaseURL);
|
|
357
|
+
if (rejected) return rejected;
|
|
344
358
|
const _url = this._createUrl(url, parameters, serviceBaseURL);
|
|
345
359
|
logger.info('DELETE', _url);
|
|
346
360
|
var req;
|
|
@@ -386,6 +400,70 @@ export default class NorthAmpliaREST {
|
|
|
386
400
|
return this._url(this._options) + '/' + this._getDefaultBaseURL(serviceBaseURL) + '/' + encode.join('/');
|
|
387
401
|
}
|
|
388
402
|
|
|
403
|
+
/**
|
|
404
|
+
* POST for a search, which reads. The search layer calls this instead of `post` so that a
|
|
405
|
+
* read-only client lets it through; the mark lasts only for the synchronous guard inside `post`.
|
|
406
|
+
* @return {Promise}
|
|
407
|
+
*/
|
|
408
|
+
_searchPost(url, data, timeout, headers, parameters, serviceBaseURL) {
|
|
409
|
+
this._searchIntent = true;
|
|
410
|
+
try {
|
|
411
|
+
return this.post(url, data, timeout, headers, parameters, serviceBaseURL);
|
|
412
|
+
} finally {
|
|
413
|
+
this._searchIntent = false;
|
|
414
|
+
}
|
|
415
|
+
}
|
|
416
|
+
|
|
417
|
+
/** @return {Promise|null} a rejection to return before sending, or null to go ahead. */
|
|
418
|
+
_guard(method, url, serviceBaseURL) {
|
|
419
|
+
return this._rejectDuplicatedBase(url, serviceBaseURL) || this._rejectWrite(method, url);
|
|
420
|
+
}
|
|
421
|
+
|
|
422
|
+
/**
|
|
423
|
+
* With `readOnly`, everything but GET and search POSTs is refused before it leaves: the search
|
|
424
|
+
* builders, and a free `post` to a `search/...` path. It guards against mistakes, not against
|
|
425
|
+
* code that holds the client and means harm -- `_searchPost` and `fetch` are one call away. The
|
|
426
|
+
* server, or a proxy in front of it, remains the boundary.
|
|
427
|
+
* @return {Promise|null}
|
|
428
|
+
*/
|
|
429
|
+
_rejectWrite(method, url) {
|
|
430
|
+
if (!this._options.readOnly || method === 'GET') return null;
|
|
431
|
+
const isSearch = this._searchIntent || (typeof url === 'string' && /^\/*search\//.test(url));
|
|
432
|
+
if (method === 'POST' && isSearch) return null;
|
|
433
|
+
|
|
434
|
+
const message = 'OGAPI: read-only client refused ' + method + ' ' + url;
|
|
435
|
+
return q.reject({
|
|
436
|
+
statusCode: 403,
|
|
437
|
+
data: { errors: [{ code: 403, message: message }] },
|
|
438
|
+
reason: 'read-only',
|
|
439
|
+
cause: new Error(message)
|
|
440
|
+
});
|
|
441
|
+
}
|
|
442
|
+
|
|
443
|
+
/**
|
|
444
|
+
* The default base (`north/v80`, or `v80` on South) is prepended to every path, so a path that
|
|
445
|
+
* repeats it, such as `/north/v80/provision/...`, used to reach `north/v80//north/v80/...` and
|
|
446
|
+
* fail with a misleading error. Such a call never worked, so refusing it breaks nothing. A
|
|
447
|
+
* caller-given `serviceBaseURL` is left alone: its paths are its own business.
|
|
448
|
+
* @return {Promise|null} a rejection to return, or null when the path is fine.
|
|
449
|
+
*/
|
|
450
|
+
_rejectDuplicatedBase(url, serviceBaseURL) {
|
|
451
|
+
if (serviceBaseURL || typeof url !== 'string') return null;
|
|
452
|
+
const base = this._getDefaultBaseURL();
|
|
453
|
+
const firstSegment = base.split('/')[0];
|
|
454
|
+
if (url.replace(/^\/+/, '').split('/')[0] !== firstSegment) return null;
|
|
455
|
+
|
|
456
|
+
const message =
|
|
457
|
+
'OGAPI: the path "' + url + '" already starts with "' + firstSegment + '/", but "' + base +
|
|
458
|
+
'/" is prepended to every path. Pass the path relative to it, or give a serviceBaseURL.';
|
|
459
|
+
return q.reject({
|
|
460
|
+
statusCode: 400,
|
|
461
|
+
data: { errors: [{ code: 400, message: message }] },
|
|
462
|
+
reason: 'invalid-path',
|
|
463
|
+
cause: new Error(message)
|
|
464
|
+
});
|
|
465
|
+
}
|
|
466
|
+
|
|
389
467
|
_getDefaultBaseURL(serviceBaseURL) {
|
|
390
468
|
if (!serviceBaseURL) {
|
|
391
469
|
if (this._isSouth) {
|
|
@@ -459,11 +537,18 @@ export default class NorthAmpliaREST {
|
|
|
459
537
|
status = 408;
|
|
460
538
|
}
|
|
461
539
|
}
|
|
462
|
-
|
|
540
|
+
const rejection = {
|
|
463
541
|
statusCode: status,
|
|
464
542
|
data: data,
|
|
465
543
|
headers: headers
|
|
466
|
-
}
|
|
544
|
+
};
|
|
545
|
+
// No response arrived. statusCode stays 500, which the web GUI handles as a generic
|
|
546
|
+
// failure; reason and cause say what actually happened.
|
|
547
|
+
if (typeof err.response === 'undefined') {
|
|
548
|
+
rejection.reason = err.reason || 'unknown';
|
|
549
|
+
rejection.cause = err;
|
|
550
|
+
}
|
|
551
|
+
defered.reject(rejection);
|
|
467
552
|
} else {
|
|
468
553
|
defered.resolve(res);
|
|
469
554
|
}
|
|
@@ -4,6 +4,21 @@ import { buildResponse, headersToObject, parseRawHeaders, toError } from './resp
|
|
|
4
4
|
import { buildFormData, packFormData } from './multipart';
|
|
5
5
|
import { match as matchMock, respond as respondMock } from './mockRouter';
|
|
6
6
|
|
|
7
|
+
/**
|
|
8
|
+
* A failure that happened before any HTTP response arrived, tagged with why: `timeout`, `aborted`
|
|
9
|
+
* or `network`. A browser reports a CORS refusal, a CSP block, a DNS failure and a dropped
|
|
10
|
+
* connection identically, so `network` cannot be split any further.
|
|
11
|
+
*/
|
|
12
|
+
function transportError(message, reason) {
|
|
13
|
+
const error = new Error(message);
|
|
14
|
+
error.reason = reason;
|
|
15
|
+
if (reason === 'timeout') {
|
|
16
|
+
error.timeout = true;
|
|
17
|
+
error.code = 'ECONNABORTED';
|
|
18
|
+
}
|
|
19
|
+
return error;
|
|
20
|
+
}
|
|
21
|
+
|
|
7
22
|
/**
|
|
8
23
|
* A request builder with superagent's shape, running on fetch.
|
|
9
24
|
*
|
|
@@ -374,7 +389,7 @@ export default class RequestSpec {
|
|
|
374
389
|
this.aborted = true;
|
|
375
390
|
this.clearTimeout();
|
|
376
391
|
if (this._xhr) this._xhr.abort();
|
|
377
|
-
else if (this._controller) this._controller.abort(
|
|
392
|
+
else if (this._controller) this._controller.abort(transportError('Request aborted', 'aborted'));
|
|
378
393
|
this.emit('abort');
|
|
379
394
|
return this;
|
|
380
395
|
}
|
|
@@ -709,7 +724,7 @@ export default class RequestSpec {
|
|
|
709
724
|
async _execute() {
|
|
710
725
|
// Checked here rather than relying on the transport to honour the signal: `abort()` may have
|
|
711
726
|
// been called from a `beforeStart` hook, before anything was sent.
|
|
712
|
-
if (this.aborted) throw
|
|
727
|
+
if (this.aborted) throw transportError('Request aborted', 'aborted');
|
|
713
728
|
|
|
714
729
|
const mocked = matchMock(this.method, this.url);
|
|
715
730
|
if (mocked) {
|
|
@@ -820,9 +835,7 @@ export default class RequestSpec {
|
|
|
820
835
|
let expire;
|
|
821
836
|
const promise = new Promise((resolve, reject) => {
|
|
822
837
|
expire = message => {
|
|
823
|
-
const error =
|
|
824
|
-
error.timeout = true;
|
|
825
|
-
error.code = 'ECONNABORTED';
|
|
838
|
+
const error = transportError(message, 'timeout');
|
|
826
839
|
this.timedout = true;
|
|
827
840
|
// Best effort, and only after the rejection is already on its way.
|
|
828
841
|
if (this._xhr) this._xhr.abort();
|
|
@@ -848,7 +861,13 @@ export default class RequestSpec {
|
|
|
848
861
|
if (controller) init.signal = controller.signal;
|
|
849
862
|
if (this._withCredentials) init.credentials = 'include';
|
|
850
863
|
|
|
851
|
-
const
|
|
864
|
+
const sent = fetch(this.url, init).catch(error => {
|
|
865
|
+
// An abort rejects with the reason we gave it, already tagged; anything else fetch
|
|
866
|
+
// throws before a response is a network failure.
|
|
867
|
+
if (error && typeof error === 'object' && !error.reason) error.reason = 'network';
|
|
868
|
+
throw error;
|
|
869
|
+
});
|
|
870
|
+
const raw = await Promise.race([sent, expiry.promise]);
|
|
852
871
|
|
|
853
872
|
// The headers are in, so the response timer has done its job; the deadline keeps running
|
|
854
873
|
// while the body is read.
|
|
@@ -895,7 +914,7 @@ export default class RequestSpec {
|
|
|
895
914
|
const xhr = new XMLHttpRequest();
|
|
896
915
|
this._xhr = xhr;
|
|
897
916
|
if (this.aborted) {
|
|
898
|
-
reject(
|
|
917
|
+
reject(transportError('Request aborted', 'aborted'));
|
|
899
918
|
return;
|
|
900
919
|
}
|
|
901
920
|
const expiry = this._expiry();
|
|
@@ -943,9 +962,9 @@ export default class RequestSpec {
|
|
|
943
962
|
if (!this._isResponseOK(response)) reject(toError(response));
|
|
944
963
|
else resolve(response);
|
|
945
964
|
};
|
|
946
|
-
xhr.onerror = () => reject(
|
|
947
|
-
xhr.ontimeout = () => reject(
|
|
948
|
-
xhr.onabort = () => reject(
|
|
965
|
+
xhr.onerror = () => reject(transportError('Network error', 'network'));
|
|
966
|
+
xhr.ontimeout = () => reject(transportError('Timeout of ' + this._timeout + 'ms exceeded', 'timeout'));
|
|
967
|
+
xhr.onabort = () => reject(transportError('Request aborted', 'aborted'));
|
|
949
968
|
|
|
950
969
|
xhr.send(body === undefined ? null : body);
|
|
951
970
|
});
|
|
@@ -1,4 +1,10 @@
|
|
|
1
|
+
/** @typedef {import('./src/InternalOpenGateAPI').OpenGateOptions} OpenGateOptions */
|
|
1
2
|
export default class OpenGateAPI extends InternalOpenGateAPI {
|
|
2
|
-
|
|
3
|
+
/**
|
|
4
|
+
* @param {import('./src/InternalOpenGateAPI').OpenGateOptions & Record<string, unknown>} _options - the client's
|
|
5
|
+
* configuration; see the README's Configuration section.
|
|
6
|
+
*/
|
|
7
|
+
constructor(_options: import("./src/InternalOpenGateAPI").OpenGateOptions & Record<string, unknown>);
|
|
3
8
|
}
|
|
9
|
+
export type OpenGateOptions = import("./src/InternalOpenGateAPI").OpenGateOptions;
|
|
4
10
|
import InternalOpenGateAPI from './src/InternalOpenGateAPI';
|
|
@@ -1,3 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What `new OpenGateAPI(options)` accepts. The README's Configuration section explains each one.
|
|
3
|
+
* @typedef {object} OpenGateOptions
|
|
4
|
+
* @property {string} url - Base URL of the North API.
|
|
5
|
+
* @property {string} [apiKey] - Sent as `X-ApiKey`.
|
|
6
|
+
* @property {string} [jwt] - Sent as `Authorization: Bearer ...`; takes precedence over `apiKey` on North calls.
|
|
7
|
+
* @property {number} [timeout] - Milliseconds. Defaults to 5000; -1 disables the timeout.
|
|
8
|
+
* @property {{url: string}} [south] - Only needed to call the South API.
|
|
9
|
+
* @property {{beforeStart?: function(object): void}} [hooks] - `beforeStart` receives each request just before it leaves.
|
|
10
|
+
* @property {object} [mocks] - Routes answered locally instead of calling OpenGate, keyed by verb and path.
|
|
11
|
+
* @property {boolean|{debug?: Function, info?: Function, warn?: Function, error?: Function}} [logger] - Where the
|
|
12
|
+
* library's own messages go: `false` silences it, `true` reports everything, or your own logger.
|
|
13
|
+
* @property {boolean} [readOnly] - Refuse every request but GET and searches before it is sent.
|
|
14
|
+
* @property {{organization: string, identifier: string, ds: string}} [_internalCountriesFilter] - Required by
|
|
15
|
+
* `newCountriesCatalog()`.
|
|
16
|
+
* @property {string} [port] - Ignored. Kept so code that passes it still type-checks.
|
|
17
|
+
* @property {string} [version] - Ignored. Kept so code that passes it still type-checks.
|
|
18
|
+
*/
|
|
1
19
|
/**
|
|
2
20
|
* This is an abstract class. It must be extended by another class that defines the backend, and it is used to make
|
|
3
21
|
* requests to the OpenGate North API from a browser or a Node.js server.
|
|
@@ -5,15 +23,11 @@
|
|
|
5
23
|
export default class InternalOpenGateAPI {
|
|
6
24
|
/**
|
|
7
25
|
* Constructor
|
|
8
|
-
* @param {
|
|
9
|
-
* @param {
|
|
26
|
+
* @param {object} northAmpliaREST - the client that sends requests to the North API.
|
|
27
|
+
* @param {object} southAmpliaREST - the client that sends requests to the South API.
|
|
28
|
+
* @param {OpenGateOptions & Record<string, unknown>} _options - the client's configuration.
|
|
10
29
|
*/
|
|
11
|
-
constructor(northAmpliaREST:
|
|
12
|
-
url: string;
|
|
13
|
-
port: string;
|
|
14
|
-
version: string;
|
|
15
|
-
apiKey: string;
|
|
16
|
-
});
|
|
30
|
+
constructor(northAmpliaREST: object, southAmpliaREST: object, _options: OpenGateOptions & Record<string, unknown>);
|
|
17
31
|
Napi: any;
|
|
18
32
|
Sapi: any;
|
|
19
33
|
EX: typeof Expression;
|
|
@@ -21,6 +35,19 @@ export default class InternalOpenGateAPI {
|
|
|
21
35
|
operations: Operations;
|
|
22
36
|
alarms: AlarmActions;
|
|
23
37
|
entityBuilder: EntityBuilder;
|
|
38
|
+
/**
|
|
39
|
+
* A new client with this one's options, and the given ones on top. The merge is shallow: an
|
|
40
|
+
* override of `south` replaces the whole object.
|
|
41
|
+
*
|
|
42
|
+
* A clone of a read-only client is read-only too, and asking for `readOnly: false` throws: code
|
|
43
|
+
* handed a read-only client cannot widen it this way. `logger` and `hooks` are process-wide, so
|
|
44
|
+
* overriding them in a clone changes them for every client.
|
|
45
|
+
* @example
|
|
46
|
+
* const widgetApi = ogapi.clone({ readOnly: true });
|
|
47
|
+
* @param {Partial<OpenGateOptions> & Record<string, unknown>} [overrides] - the options to change.
|
|
48
|
+
* @return {this}
|
|
49
|
+
*/
|
|
50
|
+
clone(overrides?: Partial<OpenGateOptions> & Record<string, unknown>): this;
|
|
24
51
|
/**
|
|
25
52
|
* This returns a util to find a user
|
|
26
53
|
* @return {UserFinder}
|
|
@@ -771,6 +798,74 @@ export default class InternalOpenGateAPI {
|
|
|
771
798
|
*/
|
|
772
799
|
devicePlansBuilder(organization: any): OrganizationPlans;
|
|
773
800
|
}
|
|
801
|
+
/**
|
|
802
|
+
* What `new OpenGateAPI(options)` accepts. The README's Configuration section explains each one.
|
|
803
|
+
*/
|
|
804
|
+
export type OpenGateOptions = {
|
|
805
|
+
/**
|
|
806
|
+
* - Base URL of the North API.
|
|
807
|
+
*/
|
|
808
|
+
url: string;
|
|
809
|
+
/**
|
|
810
|
+
* - Sent as `X-ApiKey`.
|
|
811
|
+
*/
|
|
812
|
+
apiKey?: string;
|
|
813
|
+
/**
|
|
814
|
+
* - Sent as `Authorization: Bearer ...`; takes precedence over `apiKey` on North calls.
|
|
815
|
+
*/
|
|
816
|
+
jwt?: string;
|
|
817
|
+
/**
|
|
818
|
+
* - Milliseconds. Defaults to 5000; -1 disables the timeout.
|
|
819
|
+
*/
|
|
820
|
+
timeout?: number;
|
|
821
|
+
/**
|
|
822
|
+
* - Only needed to call the South API.
|
|
823
|
+
*/
|
|
824
|
+
south?: {
|
|
825
|
+
url: string;
|
|
826
|
+
};
|
|
827
|
+
/**
|
|
828
|
+
* - `beforeStart` receives each request just before it leaves.
|
|
829
|
+
*/
|
|
830
|
+
hooks?: {
|
|
831
|
+
beforeStart?: (arg0: object) => void;
|
|
832
|
+
};
|
|
833
|
+
/**
|
|
834
|
+
* - Routes answered locally instead of calling OpenGate, keyed by verb and path.
|
|
835
|
+
*/
|
|
836
|
+
mocks?: object;
|
|
837
|
+
/**
|
|
838
|
+
* - Where the
|
|
839
|
+
* library's own messages go: `false` silences it, `true` reports everything, or your own logger.
|
|
840
|
+
*/
|
|
841
|
+
logger?: boolean | {
|
|
842
|
+
debug?: Function;
|
|
843
|
+
info?: Function;
|
|
844
|
+
warn?: Function;
|
|
845
|
+
error?: Function;
|
|
846
|
+
};
|
|
847
|
+
/**
|
|
848
|
+
* - Refuse every request but GET and searches before it is sent.
|
|
849
|
+
*/
|
|
850
|
+
readOnly?: boolean;
|
|
851
|
+
/**
|
|
852
|
+
* - Required by
|
|
853
|
+
* `newCountriesCatalog()`.
|
|
854
|
+
*/
|
|
855
|
+
_internalCountriesFilter?: {
|
|
856
|
+
organization: string;
|
|
857
|
+
identifier: string;
|
|
858
|
+
ds: string;
|
|
859
|
+
};
|
|
860
|
+
/**
|
|
861
|
+
* - Ignored. Kept so code that passes it still type-checks.
|
|
862
|
+
*/
|
|
863
|
+
port?: string;
|
|
864
|
+
/**
|
|
865
|
+
* - Ignored. Kept so code that passes it still type-checks.
|
|
866
|
+
*/
|
|
867
|
+
version?: string;
|
|
868
|
+
};
|
|
774
869
|
import Expression from './util/Expression';
|
|
775
870
|
import SelectElement from './util/SelectElement';
|
|
776
871
|
import Operations from './operations/Operations';
|
|
@@ -104,6 +104,31 @@ export default class NorthAmpliaREST {
|
|
|
104
104
|
*/
|
|
105
105
|
delete(url: string, timeout: number, headers: object, parameters: object, body: object, serviceBaseURL: string): Promise<any>;
|
|
106
106
|
_createUrl(relativeUrl: any, parameters: any, serviceBaseURL: any): string;
|
|
107
|
+
/**
|
|
108
|
+
* POST for a search, which reads. The search layer calls this instead of `post` so that a
|
|
109
|
+
* read-only client lets it through; the mark lasts only for the synchronous guard inside `post`.
|
|
110
|
+
* @return {Promise}
|
|
111
|
+
*/
|
|
112
|
+
_searchPost(url: any, data: any, timeout: any, headers: any, parameters: any, serviceBaseURL: any): Promise<any>;
|
|
113
|
+
_searchIntent: boolean;
|
|
114
|
+
/** @return {Promise|null} a rejection to return before sending, or null to go ahead. */
|
|
115
|
+
_guard(method: any, url: any, serviceBaseURL: any): Promise<any> | null;
|
|
116
|
+
/**
|
|
117
|
+
* With `readOnly`, everything but GET and search POSTs is refused before it leaves: the search
|
|
118
|
+
* builders, and a free `post` to a `search/...` path. It guards against mistakes, not against
|
|
119
|
+
* code that holds the client and means harm -- `_searchPost` and `fetch` are one call away. The
|
|
120
|
+
* server, or a proxy in front of it, remains the boundary.
|
|
121
|
+
* @return {Promise|null}
|
|
122
|
+
*/
|
|
123
|
+
_rejectWrite(method: any, url: any): Promise<any> | null;
|
|
124
|
+
/**
|
|
125
|
+
* The default base (`north/v80`, or `v80` on South) is prepended to every path, so a path that
|
|
126
|
+
* repeats it, such as `/north/v80/provision/...`, used to reach `north/v80//north/v80/...` and
|
|
127
|
+
* fail with a misleading error. Such a call never worked, so refusing it breaks nothing. A
|
|
128
|
+
* caller-given `serviceBaseURL` is left alone: its paths are its own business.
|
|
129
|
+
* @return {Promise|null} a rejection to return, or null when the path is fine.
|
|
130
|
+
*/
|
|
131
|
+
_rejectDuplicatedBase(url: any, serviceBaseURL: any): Promise<any> | null;
|
|
107
132
|
_getDefaultBaseURL(serviceBaseURL: any): any;
|
|
108
133
|
_createPromiseRequest(req: any, events: any, timeout: any, headers: any, asBlob: any): any;
|
|
109
134
|
}
|