Versioning and stability
How @unet/id-web is versioned while it is 0.x, which parts you can rely on and which are still settling, how things are deprecated, and what it needs from the browser and the server.
@unet/id-web follows semantic versioning, with the usual caveat for versions that start with 0.
While the version is 0.x
- A patch release (0.3.1) fixes bugs and does not change the API.
- A minor release (0.4.0) can add things and can contain breaking changes. Breaking changes are marked as such in the changelog and, when they need code changes, explained on a page like Upgrading from 0.2 to 0.3.
- A security fix is released as soon as it is ready, even if it breaks something. The 0.3 change to
verifyAccessTokenis an example.
Pin the version you test with ("@unet/id-web": "0.3.0" rather than a range) until 1.0, and read the changelog before you upgrade.
What is stable and what is not
The sign-in part is the foundation of the UNET web version and its shape is settled. The API client is large and parts of it are newer.
| Area | Status | Notes |
|---|---|---|
Sign-in: signIn, handleRedirectCallback, restore, getUser, signOut | Stable | The web version runs on it. |
Sessions: refresh, storage options, onSessionChange, getAccessToken | Stable | |
Errors: the classes and their code values | Stable | New codes can be added; existing ones keep their meaning. |
Server-side checks: verifyAccessToken, verifyIdToken, getIdToken | New in 0.3 | The behaviour is fixed by security reasons; options may still be extended. |
| Feed, posts, comments, profiles, search, notifications | Stable | The core of the API. |
| Likes, reposts, follows, library, safety | Stable | |
Settings (settings, updateSettings, muted keywords) | Beta | Added recently; the fields can grow. |
Realtime (api.realtime()) | Beta | The events and options can still change. |
| Fediverse calls | Beta | The newest area; expect changes. |
| Stickers, GIFs, music on profiles | Beta | |
Relationship fields on people (Profile.viewer, connectionsVisible, PersonRef.viewer) | Beta | Optional fields: a missing one is not an error. |
Beta means that the call works and is meant to stay, but its parameters, its result or its names may change in a minor release. It is announced in the changelog.
Deprecation
When something is going to be removed, it is marked deprecated in the reference and in the changelog, and keeps working for at least one minor release before it is removed. A security problem is the exception: it can be changed or removed at once.
Compatibility with the server
The SDK is written to work with older servers.
- A field that an older server does not send is typed as optional, and the changelog notes it ("absent on older servers"). Do not assume it is there.
api.realtime()against a server without streams fails with afatalerror event; keep polling in that case.- The sign-in itself needs a server whose discovery document names its own public
httpsissuer. See Upgrading from 0.2 to 0.3.
Browsers and runtimes
The SDK needs fetch, Web Crypto (on https pages and localhost), and AbortSignal.timeout() for request timeouts. Web Locks and web storage are optional. The exact list and the versions are on Installation.
The server-side checks run on Node 19 or newer, Deno, Bun and Cloudflare Workers. verifyAccessToken also works on Node 18; verifyIdToken needs --experimental-global-webcrypto there.
Reading the changelog
The changelog lists the newest version first. The section at the top, "Unreleased", is what the next release will contain. Each line starts with what kind of change it is:
| Label | Meaning |
|---|---|
| New | A new call, option or field |
| Fix | A bug fixed |
| Change | A behaviour that changed |
| Security | A security change. If it is also breaking, the line says so. |
| Build | Packaging and tooling |
Security and breaking changes are the ones to read before every upgrade.