epicenter-libs 3.34.2 → 3.35.0

package/CHANGELOG.md

@@ -1,3 +1,38 @@
+# [3.35.0](https://github.com/forio/epicenter-libs/compare/v3.34.2...v3.35.0) (2026-07-21)
+
+
+### Bug Fixes
+
+* correct privateKeySpec in examples and tests ([802ae14](https://github.com/forio/epicenter-libs/commit/802ae146edbf7c2b0c5ed8bba333546dd23b5244))
+* fix required optionals.message errors ([d7266e6](https://github.com/forio/epicenter-libs/commit/d7266e67a43f5326ed467e9d5bd13d9584a0d242))
+* resolve lockfile conflict ([ca6c8c1](https://github.com/forio/epicenter-libs/commit/ca6c8c18a49449eacf7f5620cc7fe61b1a9bb429))
+* type task payload.target, ISO failSafeTermination, doc privileges ([79f613c](https://github.com/forio/epicenter-libs/commit/79f613cbfac11c0b2ddf02095625e9cbb3836f20))
+* use a single build timestamp across all bundles ([27f8fdb](https://github.com/forio/epicenter-libs/commit/27f8fdb8795769bcdd68b1873be3b98449228872))
+
+
+### Features
+
+* complete task adapter contract ([7a8f40a](https://github.com/forio/epicenter-libs/commit/7a8f40a9c55c2881c58a30646a273b61d840e0b1))
+* add docket adapter ([c59eebf](https://github.com/forio/epicenter-libs/commit/c59eebfb27bad4ec43a17f28823bc1a95afb8182))
+* add encyclopedia adapter ([1fea349](https://github.com/forio/epicenter-libs/commit/1fea349f0b027aba1a38a1648b19a9d738566469))
+* add file adapter ([a719fd5](https://github.com/forio/epicenter-libs/commit/a719fd521efe1427ba815b418813eb6024b11278))
+* add git adapter ([20f3294](https://github.com/forio/epicenter-libs/commit/20f3294241baae88990890d4dcdfd951bf002bd6))
+* add pipeline adapter ([f3271d6](https://github.com/forio/epicenter-libs/commit/f3271d66a676d2d7e8f8a8d6069b08a9445f036a))
+* add powerpoint adapter ([7e825fd](https://github.com/forio/epicenter-libs/commit/7e825fd0d23b57f739bd984e10719d49268a4787))
+* add registration adapter ([a848097](https://github.com/forio/epicenter-libs/commit/a848097525f0cae1b6c6ac9cabe7f097c9d6d04a))
+* add taskAdapter.query wrapping GET /task/search ([d787069](https://github.com/forio/epicenter-libs/commit/d787069d29041dcbbb835595ae8a965b0c0731bb))
+
+
+### BREAKING CHANGES
+
+* `taskAdapter.getHistory()` and `taskAdapter.getTaskIn()` now resolve to a `Page` object instead of an array; read the records from `.values` (or use `.all()`/`.next()`/`.prev()`) rather than iterating the result directly.
+* `taskAdapter.getHistory()` now resolves to `TaskHistoryReadOutView` records and no longer accepts `<Body, Headers>` type parameters (it was previously typed, incorrectly, as task read views).
+* `taskAdapter.create()` `optionals.failSafeTermination` is now an ISO-8601 `string`; callers passing epoch milliseconds (`number`) must convert (e.g. `new Date(ms).toISOString()`).
+* `taskAdapter.create()` payload `body` is now required, and `payload.method` is restricted to `'GET' | 'POST' | 'PUT' | 'DELETE'` (`PATCH` and other arbitrary strings are no longer accepted).
+* `RETRY_POLICY.RESCHEDULE` has been removed (it was never accepted by the server); use `DO_NOTHING` or `FIRE_ON_FAIL_SAFE`.
+
+
+
 ## [3.34.2](https://github.com/forio/epicenter-libs/compare/v3.34.1...v3.34.2) (2026-04-01)
 
 

package/README.md

@@ -2,22 +2,15 @@
 
 The Epicenter JS libs is Forio's JavaScript library for interacting with the Epicenter platform. Similar to its [predecessor](https://github.com/forio/epicenter-js-libs), it is comprised of a set of adapters meant to help streamline your work with the underlying Epicenter APIs.
 
-If you are comfortable with JavaScript, the epicenter.js library is an easy way to connect your project's model, data, and user interface.
+If you are comfortable with JavaScript, epicenter-libs is an easy way to connect your project's model, data, and user interface.
 
 Questions? Contact us at <support@forio.com> or file an issue on github!
 
-JIRA (Forio internal): <https://issues.forio.com/projects/EPILIBS/issues>
+JIRA (Forio internal): <https://forio.atlassian.net/browse/EPILIBS>
 
 ## Table of Contents
 
-- [Transition Guide (v2 &rarr; v3)](#transition-guide-v2--v3)
-  - [New Features In v3](#new-features-in-v3)
-  - [Some Things Were Renamed](#some-things-were-renamed)
-  - [Changes In The Way We Store And Expose User Data](#changes-in-the-way-we-store-and-expose-user-data)
-  - [Session Expiration & Generic Error Handling](#session-expiration--generic-error-handling)
-  - [Built-in SSO Handling](#built-in-sso-handling)
-  - [Pagination](#pagination)
-  - [Presence](#presence)
+- [Documentation](#documentation)
 - [Tenets for Development](#tenets-for-development)
 - [How to Contribute](#how-to-contribute)
 - [How to Prepare a Release](#how-to-prepare-a-release)
@@ -28,62 +21,24 @@ JIRA (Forio internal): <https://issues.forio.com/projects/EPILIBS/issues>
     - [npm dist-tag add | rm | ls](#npm-dist-tag-add--rm--ls)
   - [Versioning](#versioning)
 - [How to Test](#how-to-test)
-- [How to Use Examples (Local)](#how-to-use-examples-local)
-  - [Vanilla JavaScript](#vanilla-javascript)
-  - [Node Server](#node-server)
-- [Documentation](#documentation)
-
-## Transition Guide (v2 &rarr; v3)
-
-### New Features In v3
-
-- All resources now have an associated scope to help categorize them -- e.g., project, group, episode, world.
-
-- All resources now have an associated permit to help define permissions for roles (anonymous, participant, leader, reviewer, facilitator)
-- Users now have a `displayName` for use in sims, detached from any private personal data
-- Two new roles for end users:
-  - reviewer: a role similar to facilitators, but lower on the permissions hierarchy
-  - leader: a role similar to participants, but higher on the permissions hierarchy
-- And more below...
-
-### Some Things Were Renamed
-
-- A bunch of user and run properties, among them --
-  - `userName → handle`
-  - `firstName → givenName`
-  - `lastName → familyName`
-  - `run.saved → run.marked`
-  - `run.trashed → run.hidden`
-
-- Resources ID'd by `[RESOURCE]Id` (e.g., `runId`) now use `key` instead of `id` (so now it's `runKey`)
-- `id` now refers to the long value of the row ID in the database instead
-- All resource `key`s are GUIDs (globally unique IDs)
-
-### Changes In The Way We Store And Expose User Data
-
-User information has been separated into out to better support for GDPR standards. Users now own a "pseudonym" from which to interact with the simulations. This is detached from their personal data which lets the platform to maintain a record while allowing for easy removal of user-sensitive data when requested.
-
-### Session Expiration & Generic Error Handling
-
-- v3 authorization tokens can now expire after a period of inactivity, and become invalid after a world assignment change
-
-- All calls have an error handling fallback to an `errorManager` instance, which will help to run checks on generic network errors like the expiration behavior described in the previous bullet
-
-### Built-in SSO Handling
-
-On load, epi-libs will now make an effort to find any Epicenter SSO tokens and consume them to generate an Epicenter session for you. This means a node server is no longer a hard requirement if you want to do SSO!
-
-### Pagination
+- [Transition Guide (v2 &rarr; v3)](#transition-guide-v2--v3)
+  - [New Features In v3](#new-features-in-v3)
+  - [Some Things Were Renamed](#some-things-were-renamed)
+  - [Changes In The Way We Store And Expose User Data](#changes-in-the-way-we-store-and-expose-user-data)
+  - [Session Expiration & Generic Error Handling](#session-expiration--generic-error-handling)
+  - [Built-in SSO Handling](#built-in-sso-handling)
+  - [Pagination](#pagination)
+  - [Presence](#presence)
 
-When retrieving records, pagination is no longer done via the request `Content-Range` header like in v2. Instead, the platform will now return a page-like object, which will contain properties that reflect the `records {start}-{end}/{total}` syntax:
+## Documentation
 
-- `first → page.firstResult`
-- `end → page.firstResult + page.maxResults`
-- `total → page.totalResults`
+epicenter-libs is documented as part of the broader [Epicenter developer docs](https://docs.forio.com/epicenter), which also cover platform topics beyond the libraries (such as Interface Builder, models, and administration). The sections most relevant to working with the libraries are:
 
-### Presence
+- [About the Libraries](https://docs.forio.com/epicenter/developer-concepts/about-the-libraries) — a higher-level overview of the libraries and the platform's core entities (worlds, groups, runs, and more).
+- [About the Reference](https://docs.forio.com/epicenter/developer-reference/about-the-reference) — reference pages for each adapter's functions and entities, push channel implementation, and other utilities.
+- [Developer Tutorials](https://docs.forio.com/epicenter/developer-tutorial/about) — ready-made starter-kit templates (single-player, multiplayer, leaderboard, and more) for getting an application up and running quickly.
 
-A user's presence is now determined by their connection to the CometD server. Unlike in v2, the platform will automatically create push channel notifications on behalf of the user when they subscribe or do anything channel related (i.e., like a CometD handshake).
+Every exported function is also documented inline with JSDoc — descriptions plus usage examples — alongside complete TypeScript type definitions, so that documentation surfaces directly in your editor through autocomplete and hover.
 
 ## Tenets for Development
 
@@ -126,7 +81,7 @@ For doing a test run before actually publishing
 
 #### npm publish --tag next
 
-For when you want to publish an alpha version of the libs for testing. Normal installations will not pick up versions tagged as "next". This way, you can publish on a change you want to test, and then go to an external project and run `npm install -i epicenter-libs@next` to go and play around with your changes.
+For when you want to publish an alpha version of the libs for testing. Normal installations will not pick up versions tagged as "next". This way, you can publish on a change you want to test, and then go to an external project and run `npm install epicenter-libs@next` to go and play around with your changes.
 
 #### npm unpublish epicenter-libs@{{version}}
 
@@ -145,40 +100,60 @@ The web development team isn't planning on incrementing the number that correlat
 Tests are written to preserve behavior across releases. These are unit tests and are not intended for testing Epicenter features themselves.
 
 ```console
-npm install             # Installs dependencies for libs
+npm ci                  # Installs dependencies for libs
 npm run build           # Builds libs to dist/ folder
 npm run test:run        # Runs the tests once
 npm run test            # Runs the tests w/ a watch
 ```
 
-Logs during testing are sent to `browser.log` file
+## Transition Guide (v2 &rarr; v3)
 
-## How to Use Examples (Local)
+### New Features In v3
 
-The following are examples of the Epicenter JS libs use cases. Their intended purpose is to be a sandbox for end-to-end testing.
+- All resources now have an associated scope to help categorize them -- e.g., project, group, episode, world.
 
-Do not use these as a starting point/template for new projects. They are not an indicator of frontend best practices, rather -- the choice to use vanilla JavaScript here was to make it universally understandable.
+- All resources now have an associated permit to help define permissions for roles (anonymous, participant, leader, reviewer, facilitator)
+- Users now have a `displayName` for use in sims, detached from any private personal data
+- Two new roles for end users:
+  - reviewer: a role similar to facilitators, but lower on the permissions hierarchy
+  - leader: a role similar to participants, but higher on the permissions hierarchy
+- And more below...
 
-### Vanilla JavaScript
+### Some Things Were Renamed
 
-```console
-npm install             # Installs dependencies for libs
-npm run build           # Builds libs to dist/ folder
-cd examples/parcel
-npm install             # Install dependencies for example
-npm start               # Serves example locally at localhost:3913
-```
+- A bunch of user and run properties, among them --
+  - `userName → handle`
+  - `firstName → givenName`
+  - `lastName → familyName`
+  - `run.saved → run.marked`
+  - `run.trashed → run.hidden`
 
-### Node Server
+- Resources ID'd by `[RESOURCE]Id` (e.g., `runId`) now use `key` instead of `id` (so now it's `runKey`)
+- `id` now refers to the long value of the row ID in the database instead
+- All resource `key`s are GUIDs (globally unique IDs)
 
-```console
-npm install             # Installs dependencies for libs
-npm run build           # Builds libs to dist/ folder
-cd examples/node
-npm install             # Install dependencies for example
-npm start
-```
+### Changes In The Way We Store And Expose User Data
 
-## Documentation
+User information has been separated out to better support GDPR standards. Users now own a "pseudonym" from which to interact with the simulations. This is detached from their personal data, which lets the platform maintain a record while allowing for easy removal of user-sensitive data when requested.
+
+### Session Expiration & Generic Error Handling
+
+- v3 authorization tokens can now expire after a period of inactivity, and become invalid after a world assignment change
+
+- All calls have an error handling fallback to an `errorManager` instance, which will help to run checks on generic network errors like the expiration behavior described in the previous bullet
 
-Documentation is currently limited. For the time being, please refer to the comments in code. Hoping to support this in a more official capacity at some point, possibly having them generated automatically with tools like [TypeDoc](https://typedoc.org/).
+### Built-in SSO Handling
+
+On load, epicenter-libs will now make an effort to find any Epicenter SSO tokens and consume them to generate an Epicenter session for you. This means a node server is no longer a hard requirement if you want to do SSO!
+
+### Pagination
+
+When retrieving records, pagination is no longer done via the request `Content-Range` header like in v2. Instead, the platform will now return a page-like object, which will contain properties that reflect the `records {start}-{end}/{total}` syntax:
+
+- `first → page.firstResult`
+- `end → page.firstResult + page.maxResults`
+- `total → page.totalResults`
+
+### Presence
+
+A user's presence is now determined by their connection to the CometD server. Unlike in v2, the platform will automatically create push channel notifications on behalf of the user when they subscribe or do anything channel related (i.e., like a CometD handshake).