opengate-js 16.0.0 → 16.1.1

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 (61) hide show
  1. package/README.md +67 -11
  2. package/dist/{opengate-api-bower-16.0.0.js → opengate-api-bower-16.1.1.js} +18099 -33518
  3. package/dist/opengate-api-bower-16.1.1.js.map +6 -0
  4. package/dist/opengate-api-bower-16.1.1.min.js +113 -0
  5. package/dist/opengate-api-bower-16.1.1.min.js.map +6 -0
  6. package/dist/opengate-api-npm.mjs +77 -70
  7. package/dist/opengate-api-npm.mjs.map +2 -2
  8. package/dist/src/operations/Operations.js +2 -2
  9. package/dist/src/operations/Operations.js.map +2 -2
  10. package/dist/src/operations/catalog/BaseOperationBuilder.js +2 -2
  11. package/dist/src/operations/catalog/BaseOperationBuilder.js.map +2 -2
  12. package/dist/src/operations/catalog/period/ExecuteEachBuilder.js +2 -2
  13. package/dist/src/operations/catalog/period/ExecuteEachBuilder.js.map +2 -2
  14. package/dist/src/operations/catalog/period/PeriodicityUpdateBuilder.js +3 -3
  15. package/dist/src/operations/catalog/period/PeriodicityUpdateBuilder.js.map +2 -2
  16. package/dist/src/operations/catalog/period/pattern/ByGeneric.js +2 -2
  17. package/dist/src/operations/catalog/period/pattern/ByGeneric.js.map +2 -2
  18. package/dist/src/provision/country/CountriesCatalog.js +2 -2
  19. package/dist/src/provision/country/CountriesCatalog.js.map +2 -2
  20. package/dist/src/provision/entities/BulkBuilder.js +18 -4
  21. package/dist/src/provision/entities/BulkBuilder.js.map +1 -1
  22. package/dist/src/provision/entities/DeviceBuilder.js +2 -2
  23. package/dist/src/provision/entities/DeviceBuilder.js.map +2 -2
  24. package/dist/src/provision/entities/EntityBuilder.js +2 -2
  25. package/dist/src/provision/entities/EntityBuilder.js.map +2 -2
  26. package/dist/src/searching/Search.js +2 -3
  27. package/dist/src/searching/Search.js.map +2 -2
  28. package/dist/src/searching/SearchWithoutLimit.js +2 -3
  29. package/dist/src/searching/SearchWithoutLimit.js.map +2 -2
  30. package/dist/src/searching/WPSearch.js +2 -3
  31. package/dist/src/searching/WPSearch.js.map +2 -2
  32. package/dist/src/searching/builder/BasicTypesSearchBuilder.js +22 -11
  33. package/dist/src/searching/builder/BasicTypesSearchBuilder.js.map +2 -2
  34. package/dist/src/searching/builder/DatapointsSearchBuilder.js +2 -2
  35. package/dist/src/searching/builder/DatapointsSearchBuilder.js.map +2 -2
  36. package/dist/src/searching/builder/SoftwaresSearchBuilder.js +2 -2
  37. package/dist/src/searching/builder/SoftwaresSearchBuilder.js.map +2 -2
  38. package/dist/src/util/NorthAmpliaREST.js +1 -2
  39. package/dist/src/util/NorthAmpliaREST.js.map +2 -2
  40. package/package.json +5 -6
  41. package/src/operations/Operations.js +2 -2
  42. package/src/operations/catalog/BaseOperationBuilder.js +2 -2
  43. package/src/operations/catalog/period/ExecuteEachBuilder.js +2 -2
  44. package/src/operations/catalog/period/PeriodicityUpdateBuilder.js +3 -3
  45. package/src/operations/catalog/period/pattern/ByGeneric.js +2 -2
  46. package/src/provision/country/CountriesCatalog.js +2 -2
  47. package/src/provision/entities/BulkBuilder.js +4 -3
  48. package/src/provision/entities/DeviceBuilder.js +2 -2
  49. package/src/provision/entities/EntityBuilder.js +2 -2
  50. package/src/searching/Search.js +2 -3
  51. package/src/searching/SearchWithoutLimit.js +2 -3
  52. package/src/searching/WPSearch.js +2 -3
  53. package/src/searching/builder/BasicTypesSearchBuilder.js +22 -11
  54. package/src/searching/builder/DatapointsSearchBuilder.js +2 -2
  55. package/src/searching/builder/SoftwaresSearchBuilder.js +2 -2
  56. package/src/util/NorthAmpliaREST.js +1 -2
  57. package/types/src/provision/entities/BulkBuilder.d.ts +1 -1
  58. package/types/src/users/Users.d.ts +1 -1
  59. package/dist/opengate-api-bower-16.0.0.js.map +0 -6
  60. package/dist/opengate-api-bower-16.0.0.min.js +0 -231
  61. package/dist/opengate-api-bower-16.0.0.min.js.map +0 -6
package/README.md CHANGED
@@ -13,6 +13,10 @@ It wraps both platform APIs behind a fluent, promise-based interface, and it is
13
13
  npm install opengate-js
14
14
  ```
15
15
 
16
+ Installing straight from the repository (a git dependency, or `yarn link` against a clone) works
17
+ too: `dist/` and `types/` are not committed, so the `prepare` script builds them at install time.
18
+ That needs the dev dependencies, so `--ignore-scripts` leaves the package without an entry point.
19
+
16
20
  ## Quick start
17
21
 
18
22
  ```js
@@ -91,16 +95,44 @@ const ogapi = new OpenGateAPI({
91
95
 
92
96
  ## In the browser
93
97
 
94
- The package ships a browserified bundle that defines `window.OpenGateAPI`:
98
+ With a bundler (Vite, webpack, Rollup, Nuxt), import the package by name. Nothing else is needed —
99
+ the same entry point serves the browser and the server:
100
+
101
+ ```js
102
+ import OpenGateAPI from 'opengate-js';
103
+
104
+ const ogapi = new OpenGateAPI({ url: 'https://opengate.example.com', apiKey: '…' });
105
+ ```
106
+
107
+ An application that expects the library on the global object needs one more line, and every other
108
+ file can keep using `window.OpenGateAPI` unchanged:
109
+
110
+ ```js
111
+ import OpenGateAPI from 'opengate-js';
112
+ window.OpenGateAPI = OpenGateAPI;
113
+ ```
114
+
115
+ Prefer this over importing the browser bundle by path: it tree-shakes, and the path does not change
116
+ with every release.
117
+
118
+ Without a bundler, the package ships a self-contained bundle that defines `window.OpenGateAPI`:
95
119
 
96
120
  ```html
97
121
  <script src="node_modules/opengate-js/dist/opengate-api-bower-16.0.0.min.js"></script>
98
122
  <script>
99
123
  var ogapi = new OpenGateAPI({ url: 'https://opengate.example.com', apiKey: '…' });
100
124
  </script>
125
+ ```
101
126
 
102
127
  The bundle carries the version in its filename, so this path changes with every release.
103
- ```
128
+
129
+ It is built for `<script src>` only. Being an IIFE it exports nothing, and importing it from a module
130
+ — `import 'opengate-js/dist/opengate-api-bower-16.0.0.js'` — throws `RangeError: Maximum call stack
131
+ size exceeded` as it evaluates: the bundle contains a `require.resolve` call that reaches esbuild's
132
+ `__require` helper, a self-referencing Proxy whose getter re-enters itself. Because `import` is
133
+ hoisted, this happens before any line of the importing file runs, so it looks as though nothing
134
+ executed at all. Use the bare `import OpenGateAPI from 'opengate-js'` above instead, which is the
135
+ supported way to reach the library from a bundler.
104
136
 
105
137
  ## Transport
106
138
 
@@ -337,7 +369,7 @@ Node, where there is no preflight, and reports only the checks where the two run
337
369
  - `test/unit/` — unit tests, including `regressions/`, which pins defects that already shipped.
338
370
  - `features/` — Cucumber acceptance suite, run against a live OpenGate.
339
371
  - `tools/apidoc/` — generates the API model and the declarations from the JSDoc.
340
- - `dist/` — build output. **Not in the repository**: run `yarn build`, and `prepack` produces it on publish.
372
+ - `dist/` — build output. **Not in the repository**: run `yarn build`, and `prepare` produces it on install and on publish.
341
373
 
342
374
  ## Testing
343
375
 
@@ -356,18 +388,42 @@ yarn build && yarn test:e2e [--tags @tag]
356
388
  Certificate verification is disabled for that run, because test instances tend to carry self-signed
357
389
  certificates. Set `OGAPI_E2E_STRICT_TLS=1` to keep it on.
358
390
 
359
- ## Releasing
391
+ ## Branching and releasing
392
+
393
+ Work happens on a branch off `develop`, named after its ticket (`OUW-4887`) or its intent
394
+ (`docs/release-flow`), and reaches `develop` through a pull request. CI lints and runs the unit suite
395
+ on Node 20, 22 and 24 — on the pull request, and again on the merge. `develop` is where a change is
396
+ proven; nothing is released from a red `develop`.
397
+
398
+ A release is cut from `master`, which is only ever fast-forwarded to a green `develop`:
399
+
400
+ 1. Bump `version` in `package.json` on `develop`, commit, push, and wait for CI. This bump is the
401
+ one commit that goes straight onto `develop` rather than through a pull request.
402
+ 2. Fast-forward `master` onto `develop`.
403
+ 3. Tag that commit `vX.Y.Z`, matching the version exactly, and push the tag.
404
+
405
+ ```bash
406
+ git checkout develop && git pull
407
+ # bump "version" in package.json
408
+ git commit -am "release minor version:16.1.0"
409
+ git push origin develop
410
+
411
+ # 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
415
+ ```
360
416
 
361
- Publication to [npm](https://www.npmjs.com/package/opengate-js) is driven by the tag and by nothing else:
417
+ **Pushing the tag is what publishes, and nothing else is.** Nobody runs `npm publish` by hand.
362
418
 
363
- 1. Bump `version` in `package.json` on `develop`, and commit.
364
- 2. Tag that commit `vX.Y.Z`, matching the version exactly.
365
- 3. Push the tag.
419
+ Keep the `--ff-only`, and never commit to `master` directly. The moment `master` carries a commit
420
+ `develop` does not, the two diverge and every later release needs a merge by hand. Tags up to
421
+ `v16.0.0` predate this rule and point at `develop` commits, from a period when `master` had been left
422
+ behind at `14.15.0`.
366
423
 
367
- Releases are tagged on `develop`. `master` is frozen at `14.15.0` and is not the release branch. There
368
- is no `bower.json` any more, despite the name of the browser bundle.
424
+ There is no `bower.json` any more, despite the name of the browser bundle.
369
425
 
370
- `.github/workflows/release.yml` refuses to continue if the tag and `package.json` disagree, then lints, tests, regenerates the declarations through `prepack`, publishes with [provenance](https://docs.npmjs.com/generating-provenance-statements), and opens a GitHub release carrying `api-model.json`.
426
+ `.github/workflows/release.yml` refuses to continue if the tag and `package.json` disagree, then lints, tests, regenerates the declarations through `prepare`, publishes with [provenance](https://docs.npmjs.com/generating-provenance-statements), and opens a GitHub release carrying `api-model.json`. It fires on any `v*` tag, whatever branch it sits on — the discipline above is what keeps that meaningful.
371
427
 
372
428
  It needs one repository secret, `NPM_TOKEN`: an npm automation token with publish rights.
373
429