Client library

Client reference

Every method of @thuum/client, the flag and validation helpers, token helpers, errors and exported types.

ThuumClient#

Method	Returns
`new ThuumClient({ baseUrl, fetch? })`
`exchangeToken(domain, appKey, { scope?, ttl_seconds? })`	`{ token, token_type, expires_in }`
`domain(domain, token, { onError? })`	`DomainClient`
`request(method, path, { token?, body? })`	the response's `data` (`undefined` for `204`)

DomainClient#

slug is the Domain. me() returns Me.

`eventBroker`#

Method	Route	Returns
`data.publish(topic, { type, data })`	`POST /event/data/{topic}`	`BrokerEvent`
`data.list(topic, { type?, since?, until?, limit? })`	`GET /event/data/{topic}`	`BrokerEvent[]`
`data.purge(topic, { type?, since?, until? })`	`DELETE /event/data/{topic}`	`{ deleted }`
`topics.list()`	`GET /event/topics`	`Topic[]`
`topics.get(mainTopic)`	`GET /event/topics/{topic}`	`Topic`
`topics.put(mainTopic, { max_events?, ttl_seconds? })`	`PUT /event/topics/{topic}`	`Topic`
`topics.delete(mainTopic)`	`DELETE /event/topics/{topic}`	—
`connect({ WebSocket? })`	WebSocket	`EventBrokerSocket`
`claims.list()` / `get(id)`	`GET /event/claims[/{id}]`	`EventClaim[]` / `EventClaim`
`claims.create({ name, description?, topic_flags?, fallback_data_flags?, topics? })`	`POST /event/claims`	`EventClaim`
`claims.update(id, fields)` / `delete(id)`	`PATCH` / `DELETE /event/claims/{id}`	`EventClaim` / —
`claims.topics.put(id, mainTopic, flags)` / `delete(id, mainTopic)`	`…/claims/{id}/topics/{topic}`	`EventClaim` / —
`claims.keys.link(id, selector)` / `unlink(id, selector)`	`…/claims/{id}/keys/{selector}`	`EventClaim` / —
`keys.list()`	`GET /event/keys`	`EventKey[]`

`stateBroker`#

Method	Route	Returns
`data.get(topic, key)`	`GET /state/data/{topic}/{key}`	`BrokerState`
`data.list(topic, { prefix?, after?, after_topic?, limit? })`	`GET /state/data/{topic}`	`BrokerState[]`
`data.set(topic, key, value)`	`PUT /state/data/{topic}/{key}`	`BrokerState`
`data.merge(topic, key, patch)`	`PATCH /state/data/{topic}/{key}`	`BrokerState`
`data.delete(topic, key)`	`DELETE /state/data/{topic}/{key}`	—
`data.echo(topic, key)`	`POST /state/data/{topic}/{key}/echo`	`BrokerState`
`topics.list()` / `get` / `put(mainTopic, { ttl_seconds?, max_states? })` / `delete`	`/state/topics…`	`StateTopic`
`connect({ WebSocket? })`	WebSocket	`StateBrokerSocket`
`claims.*`, `keys.list()`	as for the Event Broker, under `/state`	`StateClaim`, `StateKey`

`domain`#

Method	Route	Returns
`keys.list()` / `get(selector)`	`GET /domain/keys[/{selector}]`	`AppKey[]` / `AppKey`
`keys.create({ name, token_ttl_seconds? })`	`POST /domain/keys`	`CreatedAppKey` (with `key`)
`keys.delete(selector)`	`DELETE /domain/keys/{selector}`	—
`claims.list()` / `get(id)`	`GET /domain/claims[/{id}]`	`DomainClaim[]` / `DomainClaim`
`claims.create({ name, description?, protocols? })`	`POST /domain/claims`	`DomainClaim`
`claims.update(id, { name?, description? })` / `delete(id)`	`PATCH` / `DELETE /domain/claims/{id}`	`DomainClaim` / —
`claims.protocols.put(id, protocol, flags)` / `delete(id, protocol)`	`…/protocols/{protocol}`	`DomainClaim` / —
`claims.keys.link(id, selector)` / `unlink(id, selector)`	`…/keys/{selector}`	`DomainClaim` / —

Flags#

TypeScript

import {
	PUBLISH,
	WRITE,
	SUBSCRIBE,
	READ,
	combine,
	has,
	DATA_FLAGS,
	MANAGEMENT_FLAGS
} from '@thuum/client';

Export	Value / use
`PUBLISH`, `WRITE`, `SUBSCRIBE`, `READ`	`8`, `4`, `2`, `1`
`combine(...bits)`	`combine(PUBLISH, READ) === 9`
`has(flags, bit)`	Whether `flags` includes every bit of `bit`.
`DATA_FLAGS`	`[{ bit, letter, label }]` for `P W S R`, in order.
`MANAGEMENT_FLAGS`	The same for `W R` only.

Rules#

Validate before a round trip, with the same rules as the API:

Export	Checks
`isTopic`, `TOPIC_PATTERN`	1–8 levels of `a-z A-Z 0-9 _ -` joined by `:`, ≤ 128 characters.
`isMainTopic`, `MAIN_TOPIC_PATTERN`	One level.
`isEventType`, `EVENT_TYPE_PATTERN`	1–64 of `a-z A-Z 0-9 _ . : -`.
`isStateKey`, `STATE_KEY_PATTERN`	1–128 of `a-z A-Z 0-9 _ . : -`.
`isDomainSlug`, `isAppKey`, `isSelector`	A Domain slug, an 80-hex App Key, a 16-hex selector.
`MAX_TOPIC_LEVELS`, `MAX_TOPIC_LENGTH`	`8`, `128`.
`DEFAULT_TOKEN_TTL_SECONDS`, `MAX_TOKEN_TTL_SECONDS`	`30`, `86400`.
`mainTopic(topic)`	`'a:b:c'` ⇒ `'a'`.
`superTopics(topic)`	`'a:b:c'` ⇒ `['a:b:c', 'a:b', 'a']`: everyone a publish reaches.
`isInSubtree(topic, root)`	Whether a subscription to `root` receives `topic`.
`resolveDataFlags(claim, topic)`	`{ flags, source: 'topic' \| 'fallback', mainTopic }`, as the server resolves it.
`selectorOf(appKey)`	The first 16 characters.
`PROTOCOLS`	`['domain', 'event', 'state']`.

Tokens#

Export	Use
`decodeToken(token)`	`{ selector, expiresAt, issuedAt }` (epoch ms), or `null`. Not verified.
`isExpired(claims, now?)`	Whether decoded claims are past their expiry.

TypeScript

const claims = decodeToken(token);
if (!claims || isExpired(claims)) token = await fetchNewToken();

Types#

All request and response shapes are exported as types: BrokerEvent, BrokerState, StateChange, StateValue, Topic, StateTopic, EventFilters, PurgeFilters, StateFilters, PublishEvent, Me, AppKey, CreatedAppKey, DomainClaim, EventClaim, StateClaim, EventKey, StateKey, Protocol, TokenResponse, ApiErrors, and the option types of every class.