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
package/README.md CHANGED
@@ -45,6 +45,25 @@ try {
45
45
 
46
46
  Note that a rejection is a plain object today, not an `Error`. That is a known wart, on the list for the next major version.
47
47
 
48
+ When no answer arrives at all, `statusCode` is `500` and `data` holds a generic message, as it always has. Two more fields say
49
+ what actually happened:
50
+
51
+ ```js
52
+ try {
53
+ await ogapi.Napi.get('provision/organizations');
54
+ } catch (error) {
55
+ error.statusCode; // 500
56
+ error.reason; // 'timeout', 'aborted', 'network' or 'unknown'
57
+ error.cause; // the original Error
58
+ }
59
+ ```
60
+
61
+ `network` covers a refused connection, a DNS failure and, in a browser, a CORS or CSP block: the browser reports all of them
62
+ the same way, so the library cannot tell them apart. `reason` and `cause` are absent whenever the platform did answer.
63
+
64
+ A path given to `ogapi.Napi` is relative to `north/v80/`. One that repeats it, such as `/north/v80/provision/...`, is
65
+ rejected before it is sent, with `statusCode` `400` and `reason: 'invalid-path'`.
66
+
48
67
  ## Configuration
49
68
 
50
69
  | Option | Meaning |
@@ -58,6 +77,40 @@ Note that a rejection is a plain object today, not an `Error`. That is a known w
58
77
  | `mocks` | Answers matching requests locally instead of calling OpenGate — see [Transport](#transport). |
59
78
  | `_internalCountriesFilter` | Required by `newCountriesCatalog()`; see its JSDoc. `{ organization, identifier, ds }`. |
60
79
  | `logger` | Where the library's own messages go. `false` silences it, `true` reports everything — see [Logging](#logging). |
80
+ | `readOnly` | `true` refuses every request but GET and searches, before it leaves — see [Read-only clients](#read-only-clients). |
81
+
82
+ ### Read-only clients
83
+
84
+ For code that should only look, such as a dashboard widget or code written by a model, pass `readOnly: true`. GET requests and
85
+ searches go through: every search builder, and `ogapi.Napi.post` to a `search/...` path. Anything else, North or South, is
86
+ rejected before it is sent:
87
+
88
+ ```js
89
+ const ogapi = new OpenGateAPI({ url: 'https://opengate.example.com', apiKey: process.env.OPENGATE_API_KEY, readOnly: true });
90
+
91
+ try {
92
+ await ogapi.Napi.delete('provision/organizations/my-organization/devices/my-device');
93
+ } catch (error) {
94
+ error.statusCode; // 403
95
+ error.reason; // 'read-only'
96
+ }
97
+ ```
98
+
99
+ It prevents mistakes, not misuse. Code that holds the client can still reach the network some other way, so the permissions
100
+ that actually protect the data belong to the key or token you hand it, and to the server or proxy in front of it.
101
+
102
+ ### Cloning a client
103
+
104
+ `ogapi.clone(overrides)` returns a new client with the same options and the given ones on top. The usual case is handing a
105
+ widget a read-only copy of the client you already have, without repeating its configuration:
106
+
107
+ ```js
108
+ const widgetApi = ogapi.clone({ readOnly: true });
109
+ ```
110
+
111
+ A clone of a read-only client is read-only too, and `clone({ readOnly: false })` on it throws. The merge is shallow, so an
112
+ override of `south` replaces the whole object. `logger` and `hooks` are process-wide: overriding them in a clone changes them
113
+ for every client.
61
114
 
62
115
  ## What it covers
63
116
 
@@ -237,6 +290,17 @@ the life of the process.
237
290
 
238
291
  Type declarations ship with the package and are generated from the JSDoc in `src/`, so they always describe the version you installed. No `@types/` package needed.
239
292
 
293
+ The constructor's options are typed as `OpenGateOptions`, the [Configuration](#configuration) table above:
294
+
295
+ ```ts
296
+ import OpenGateAPI, { type OpenGateOptions } from 'opengate-js';
297
+
298
+ const options: OpenGateOptions = { url: 'https://opengate.example.com', apiKey: process.env.OPENGATE_API_KEY, timeout: 30000 };
299
+ const ogapi = new OpenGateAPI(options);
300
+ ```
301
+
302
+ Keys the type does not list are still accepted, so code that passed extra options keeps compiling.
303
+
240
304
  ## Documentation
241
305
 
242
306
  The published reference lives at **[documentation.opengate.es/libs/ogapi-docs](https://documentation.opengate.es/libs/ogapi-docs/index.html)**, and it is generated from this repository: the reference documentation **is** the JSDoc in `src/`. `tools/apidoc` turns it into a neutral API model and into the `.d.ts` files, so a wording fix belongs in `src/` and never downstream — see [tools/apidoc/README.md](tools/apidoc/README.md).
@@ -395,26 +459,38 @@ Work happens on a branch off `develop`, named after its ticket (`OUW-4887`) or i
395
459
  on Node 20, 22 and 24 — on the pull request, and again on the merge. `develop` is where a change is
396
460
  proven; nothing is released from a red `develop`.
397
461
 
462
+ Every pull request also gets a **Package diff** comment: the package is built from the base branch and
463
+ from the pull request, and `dist/`, `types/` and the API model are compared. That is the question a
464
+ dependency bump raises. "No change" means it cannot reach consumers, and a green CI is enough to merge
465
+ it. Otherwise the comment names the files, and the packages inlined in the browser bundle, that moved.
466
+ `node scripts/package-diff.mjs <base-dir> <head-dir>` runs the same comparison locally.
467
+
398
468
  A release is cut from `master`, which is only ever fast-forwarded to a green `develop`:
399
469
 
400
470
  1. Bump `version` in `package.json` on `develop`, commit, push, and wait for CI. This bump is the
401
471
  one commit that goes straight onto `develop` rather than through a pull request.
402
472
  2. Fast-forward `master` onto `develop`.
403
- 3. Tag that commit `vX.Y.Z`, matching the version exactly, and push the tag.
473
+ 3. Tag that commit `vX.Y.Z`, matching the version exactly, and push the tag by name.
404
474
 
405
475
  ```bash
406
476
  git checkout develop && git pull
407
- # bump "version" in package.json
408
- git commit -am "release minor version:16.1.0"
477
+ npm version minor --no-git-tag-version
478
+ git commit -am "release minor version:16.2.0"
409
479
  git push origin develop
410
480
 
411
481
  # once develop is green
412
- git checkout master && git merge --ff-only develop
413
- git tag v16.1.0
414
- git push origin master --follow-tags
482
+ git checkout master && git pull && git merge --ff-only develop
483
+ git push origin master
484
+ git tag -a v16.2.0 -m "release 16.2.0"
485
+ git push origin v16.2.0
415
486
  ```
416
487
 
417
- **Pushing the tag is what publishes, and nothing else is.** Nobody runs `npm publish` by hand.
488
+ **Pushing the tag is what publishes, and nothing else is.** Nobody runs `npm publish` by hand. Push it
489
+ by name: `--follow-tags` skips lightweight tags without a word, which leaves the tag on your machine
490
+ and nothing published.
491
+
492
+ [docs/RELEASING.md](docs/RELEASING.md) walks through each step, how to check that the release shipped,
493
+ and what to do when the Release workflow fails.
418
494
 
419
495
  Keep the `--ff-only`, and never commit to `master` directly. The moment `master` carries a commit
420
496
  `develop` does not, the two diverge and every later release needs a merge by hand. Tags up to
@@ -433,4 +509,4 @@ It needs one repository secret, `NPM_TOKEN`: an npm automation token with publis
433
509
 
434
510
  ## License
435
511
 
436
- ISC. See [LICENSE](LICENSE).
512
+ Apache License 2.0. See [LICENSE](LICENSE).