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.
Files changed (40) hide show
  1. package/README.md +84 -8
  2. package/dist/{opengate-api-bower-16.2.0.js → opengate-api-bower-16.3.0.js} +1006 -665
  3. package/dist/opengate-api-bower-16.3.0.js.map +6 -0
  4. package/dist/opengate-api-bower-16.3.0.min.js +117 -0
  5. package/dist/opengate-api-bower-16.3.0.min.js.map +6 -0
  6. package/dist/opengate-api-npm.js +4 -0
  7. package/dist/opengate-api-npm.js.map +1 -1
  8. package/dist/opengate-api-npm.mjs +133 -21
  9. package/dist/opengate-api-npm.mjs.map +1 -1
  10. package/dist/src/InternalOpenGateAPI.js +38 -2
  11. package/dist/src/InternalOpenGateAPI.js.map +1 -1
  12. package/dist/src/searching/AssetSearch.js +1 -1
  13. package/dist/src/searching/AssetSearch.js.map +1 -1
  14. package/dist/src/searching/BaseSearch.js +3 -3
  15. package/dist/src/searching/DeviceSearch.js +1 -1
  16. package/dist/src/searching/DeviceSearch.js.map +1 -1
  17. package/dist/src/searching/EntitySearch.js +1 -1
  18. package/dist/src/searching/EntitySearch.js.map +1 -1
  19. package/dist/src/searching/WPSearch.js +1 -1
  20. package/dist/src/searching/WPSearch.js.map +1 -1
  21. package/dist/src/util/NorthAmpliaREST.js +77 -2
  22. package/dist/src/util/NorthAmpliaREST.js.map +1 -1
  23. package/dist/src/util/http/RequestSpec.js +21 -10
  24. package/dist/src/util/http/RequestSpec.js.map +1 -1
  25. package/opengate-api-npm.js +6 -0
  26. package/package.json +2 -2
  27. package/src/InternalOpenGateAPI.js +46 -2
  28. package/src/searching/AssetSearch.js +1 -1
  29. package/src/searching/BaseSearch.js +3 -3
  30. package/src/searching/DeviceSearch.js +1 -1
  31. package/src/searching/EntitySearch.js +1 -1
  32. package/src/searching/WPSearch.js +1 -1
  33. package/src/util/NorthAmpliaREST.js +87 -2
  34. package/src/util/http/RequestSpec.js +29 -10
  35. package/types/opengate-api-npm.d.ts +7 -1
  36. package/types/src/InternalOpenGateAPI.d.ts +103 -8
  37. package/types/src/util/NorthAmpliaREST.d.ts +25 -0
  38. package/dist/opengate-api-bower-16.2.0.js.map +0 -6
  39. package/dist/opengate-api-bower-16.2.0.min.js +0 -116
  40. package/dist/opengate-api-bower-16.2.0.min.js.map +0 -6
@@ -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.2.0",
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": "ISC",
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 {{ url: string,port: string,version: string,apiKey: string}} _options - this is configuration about Opengate North API.
187
- * @param {AmpliaREST} ampliaREST - this is a backend selected to manage a request to Opengate North API.
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.post(this._resource, this._filter(), this._timeout, this._getExtraHeaders(), parameters)
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.post(
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.post(
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.post(
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.post(this._resource, this._filter(), this._timeout, this._getExtraHeaders(), parameters)
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.post(this._resource, this._filter(), this._timeout, this._getExtraHeaders(), parameters)
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.post(_this._resource, filter, _this._timeout, _this._getExtraHeaders(), _this._getUrlParameters())
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
- defered.reject({
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(new Error('Request aborted'));
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 new Error('Request aborted');
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 = new Error(message);
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 raw = await Promise.race([fetch(this.url, init), expiry.promise]);
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(new Error('Request aborted'));
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(new Error('Network error'));
947
- xhr.ontimeout = () => reject(new Error('Timeout of ' + this._timeout + 'ms exceeded'));
948
- xhr.onabort = () => reject(new Error('Request aborted'));
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
- constructor(_options: any);
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 {{ url: string,port: string,version: string,apiKey: string}} _options - this is configuration about Opengate North API.
9
- * @param {AmpliaREST} ampliaREST - this is a backend selected to manage a request to Opengate North API.
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: any, southAmpliaREST: any, _options: {
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
  }