Options

Every option of the UnetId client, signIn, the API client, realtime streams and the server-side checks: type, default, units and meaning, from the source.

Times are in milliseconds unless a name says otherwise. A default of "none" means the option is off or not set.

UnetId

new UnetId(options). Throws UnetIdError with code config if clientId or redirectUri is missing, or if issuer is not an https address (http is accepted only for localhost, 127.0.0.1 and [::1]).

Option	Type	Default	Meaning
`clientId`	`string`	required	The App ID of a public app from the console.
`redirectUri`	`string`	required	The page that calls `handleRedirectCallback()`. It must be registered as a return URL, character for character.
`scopes`	`string[]`	`["openid", "profile"]`	Permissions to ask for. `openid` is added if you leave it out. Add `offline_access` for a refresh token.
`issuer`	`string`	`https://api.unet.ovh/oidc`	The OpenID provider. A trailing slash is removed. Use the test server's address for tests.
`storage`	`"session"`, `"local"`, `"memory"`, or a `KeyValueStore`	`"session"`	Where the session lives. `"session"`: cleared when the tab closes. `"local"`: survives restarts and is shared and synchronised between tabs, but readable by any script on your origin. `"memory"`: lost on reload.
`fetch`	`typeof fetch`	global `fetch`	The function every request goes through. For tests and special environments.
`apiBase`	`string`	the issuer without its `/oidc` ending	The address of the UNET API that `unet.api` and avatar addresses use.
`onTrace`	`(trace: Trace) => void`	none	Called after every HTTP request the SDK makes, with secrets shortened. See Trace.
`navigate`	`(url: string) => void`	`location.assign`	How the browser is sent to unet.social. Mostly for tests.
`timeoutMs`	`number`	`60000`	A JSON request that takes longer fails with `NetworkError`. `0` turns it off. File uploads, media downloads and realtime streams have no timeout.
`retries`	`number`	`0`	How often the SDK retries an API request that got a 429 (any call: it was not processed) or a 5xx (GET calls only). Token requests are not retried.
`maxRetryDelayMs`	`number`	`30000`	The longest wait before one retry. The wait is `Retry-After` for a 429 when the server sends it, otherwise it doubles each time (1 s, 2 s, 4 s, ...; for a 5xx it starts at 0.5 s).

Methods with options

Call	Option	Default	Meaning
`restore(options)`	`revalidate`	`true`	`false`: trust the cached profile and make no request on startup. The tokens still refresh on first use.
`getAccessToken(force)`	`force`	`false`	`true`: refresh now, even if the token is still valid.

KeyValueStore

Pass your own object as storage to keep the session somewhere else. All three methods are synchronous.

Method	Meaning
`get(key: string): string or null`	Read a value.
`set(key: string, value: string): void`	Write a value.
`remove(key: string): void`	Delete a value.

MemoryStore is the in-memory implementation. The SDK's keys start with unet-id: followed by the App ID.

unet.signIn(options). Every field is optional.

Option	Type	Default	Meaning
`returnTo`	`string`	`"/"`	Where your app sends the person after the callback. The SDK keeps it while they are away and returns it from `handleRedirectCallback()`.
`prompt`	`"none"`, `"login"`, `"consent"`, `"select_account"`	`"consent"` if `offline_access` is in `scopes`, otherwise none	The OpenID Connect `prompt`. `"consent"` shows the permission screen again, for when you now ask for more. `"none"` shows no screen and fails if one would be needed.
`loginHint`	`string`	none	Pre-fills the account on the sign-in page.
`extraParams`	`Record<string, string>`	none	More parameters for the authorization request. The protocol ones (`client_id`, `redirect_uri`, `response_type`, `scope`, `state`, `code_challenge`, `code_challenge_method`) cannot be overridden.

The API client

unet.api takes its settings from UnetId (timeoutMs, retries, maxRetryDelayMs). unet.api.withSignal(signal) returns an API client that also carries an AbortSignal:

Option	Type	Default	Meaning
`retries`	`number`	`0`	As above.
`maxRetryDelayMs`	`number`	`30000`	As above.
`signal`	`AbortSignal`	none	Aborting it cancels the call and rejects it with the abort error, not a `NetworkError`.

Realtime

unet.api.realtime(options). At least one of notifications, posts and feeds should be given.

Option	Type	Default	Meaning
`notifications`	`boolean`	`false`	New notifications for the person. Needs `notifications:read`.
`posts`	`number[]`	none	Posts you are showing. Up to 12, each one the person may see. Needs `content:read`.
`feeds`	`Array<"global" or "following">`	none	A new post appeared in the feed. Needs `content:read`.
`minDelayMs`	`number`	`1000`	The first wait before a reconnect.
`maxDelayMs`	`number`	`30000`	The wait doubles each time up to this.

Server-side checks

verifyAccessToken

verifyAccessToken(accessToken, options): for the server of a website app. Resolves to the user (with scopes and expiresAt, in epoch milliseconds), or null.

Option	Type	Default	Meaning
`clientId`	`string`	required	Your App ID.
`clientSecret`	`string`	required	Your App Secret. Keep it on the server.
`issuer`	`string`	`https://api.unet.ovh/oidc`	The provider.
`fetch`	`typeof fetch`	global `fetch`	For tests or another runtime.
`profile`	`boolean`	`true`	`false` skips the profile request, so you get `sub`, `scopes` and `expiresAt` only.

A token longer than 2048 characters is null without a request.

verifyIdToken

verifyIdToken(idToken, options): for the server of a single-page site or app. Resolves to the claims, or null.

Option	Type	Default	Meaning
`clientId`	`string`	required	The App ID the token must have been made for.
`issuer`	`string`	`https://api.unet.ovh/oidc`	The provider.
`fetch`	`typeof fetch`	global `fetch`	For tests or another runtime.
`clockToleranceSeconds`	`number`	`60`	How much clock difference is accepted on `exp`, `iat` and `nbf`, in seconds.
`now`	`() => number`	`Date.now`	The clock, in milliseconds. For tests.

A token longer than 8192 characters is null without a request. The signing keys are cached for 10 minutes. An unknown key id triggers at most one new fetch every 30 seconds. clearIdTokenKeyCache() empties the cache.

Trace

The object onTrace receives for each request.

Field	Type	Meaning
`id`	`number`	A counter, from 1.
`at`	`number`	When the request started, in epoch milliseconds.
`ms`	`number`	How long it took.
`sdk`	`string`	Which SDK call caused it, such as `api.feed()` or `token (refresh_token)`.
`method`, `url`	`string`	The request.
`requestHeaders`, `requestBody`		The request, with the token shortened. Files are described, never included.
`status`, `ok`	`number`, `boolean`	The answer. `status` is `0` if there was none.
`responseHeaders`, `responseBody`		The answer. Media files are not read.
`error`	`string`	Set when the request failed without an answer.

Tokens, codes, verifiers and secrets are shortened to their first characters and their length.