opengate-js 16.1.2 → 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 (48) hide show
  1. package/README.md +84 -8
  2. package/dist/{opengate-api-bower-16.1.2.js → opengate-api-bower-16.3.0.js} +1493 -1153
  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 +167 -56
  9. package/dist/opengate-api-npm.mjs.map +2 -2
  10. package/dist/src/InternalOpenGateAPI.js +38 -2
  11. package/dist/src/InternalOpenGateAPI.js.map +1 -1
  12. package/dist/src/notebookScheduler/NotebookScheduler.js +13 -0
  13. package/dist/src/notebookScheduler/NotebookScheduler.js.map +1 -1
  14. package/dist/src/searching/AssetSearch.js +1 -1
  15. package/dist/src/searching/AssetSearch.js.map +1 -1
  16. package/dist/src/searching/BaseSearch.js +3 -3
  17. package/dist/src/searching/DeviceSearch.js +1 -1
  18. package/dist/src/searching/DeviceSearch.js.map +1 -1
  19. package/dist/src/searching/EntitySearch.js +1 -1
  20. package/dist/src/searching/EntitySearch.js.map +1 -1
  21. package/dist/src/searching/WPSearch.js +1 -1
  22. package/dist/src/searching/WPSearch.js.map +1 -1
  23. package/dist/src/security/Certificates.js +0 -14
  24. package/dist/src/security/Certificates.js.map +1 -1
  25. package/dist/src/util/NorthAmpliaREST.js +77 -2
  26. package/dist/src/util/NorthAmpliaREST.js.map +1 -1
  27. package/dist/src/util/http/RequestSpec.js +21 -10
  28. package/dist/src/util/http/RequestSpec.js.map +1 -1
  29. package/opengate-api-npm.js +6 -0
  30. package/package.json +2 -2
  31. package/src/InternalOpenGateAPI.js +46 -2
  32. package/src/notebookScheduler/NotebookScheduler.js +14 -0
  33. package/src/searching/AssetSearch.js +1 -1
  34. package/src/searching/BaseSearch.js +3 -3
  35. package/src/searching/DeviceSearch.js +1 -1
  36. package/src/searching/EntitySearch.js +1 -1
  37. package/src/searching/WPSearch.js +1 -1
  38. package/src/security/Certificates.js +0 -32
  39. package/src/util/NorthAmpliaREST.js +87 -2
  40. package/src/util/http/RequestSpec.js +29 -10
  41. package/types/opengate-api-npm.d.ts +7 -1
  42. package/types/src/InternalOpenGateAPI.d.ts +103 -8
  43. package/types/src/notebookScheduler/NotebookScheduler.d.ts +7 -0
  44. package/types/src/security/Certificates.d.ts +0 -1
  45. package/types/src/util/NorthAmpliaREST.d.ts +25 -0
  46. package/dist/opengate-api-bower-16.1.2.js.map +0 -6
  47. package/dist/opengate-api-bower-16.1.2.min.js +0 -116
  48. package/dist/opengate-api-bower-16.1.2.min.js.map +0 -6
@@ -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';
@@ -43,6 +43,13 @@ export default class NotebookScheduler extends BaseProvision {
43
43
  */
44
44
  withReportRetentionDays(reportRetentionDays: number): NotebookScheduler;
45
45
  _reportRetentionDays: number;
46
+ /**
47
+ * Sets the timezone attribute
48
+ * @param {string} timezone
49
+ * @return {NotebookScheduler}
50
+ */
51
+ withTimezone(timezone: string): NotebookScheduler;
52
+ _timezone: string;
46
53
  withParams(params: any): this;
47
54
  _params: any;
48
55
  _composeElement(): {
@@ -42,7 +42,6 @@ export default class Certificates extends Security {
42
42
  */
43
43
  withUsages(usages: any[]): Certificates;
44
44
  _usages: any[];
45
- _checkHardware(hardware: any): boolean;
46
45
  /**
47
46
  * Set the tags attribute
48
47
  * @param {Array} tags
@@ -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
  }