@decentrl/sdk

npm install @decentrl/sdk zod

import { defineDecentrlApp } from '@decentrl/sdk'

function defineDecentrlApp<TEvents, TState, TPublicEvents = {}, TChannels = {}>(config: {
  events: TEvents
  publicEvents?: TPublicEvents
  channels?: TChannels
  state: {
    [K in keyof TState]: {
      initial: TState[K]
      reduce: SliceReducers<TState[K], AppTypes<TEvents, TPublicEvents, TChannels, TState>>
    }
  }
}): DecentrlApp<AppTypes<TEvents, TPublicEvents, TChannels, TState>>

interface DecentrlApp<T extends AppTypes> {
  config: AppConfig<T>
  createClient(clientConfig: DecentrlClientConfig): DecentrlClient<T>
}

interface EventDefinition<TSchema extends z.ZodType = z.ZodType> {
  schema: TSchema       // validated on publish and on every received event
  tags: string[]        // template strings like "chat.${chatId}"
  groupTags?: string[]  // group tag templates like "thread.${threadId}", evaluated on client.groups.publish (at most 8)
}
type EventDefinitions = Record<string, EventDefinition>

interface ChannelDefinition<TSchema extends z.ZodType = z.ZodType> {
  schema: TSchema
}
type ChannelDefinitions = Record<string, ChannelDefinition>

// One optional reducer per key:
//   'type'            (state: TSlice, data: z.output of events[type],       meta: EventMeta)       => TSlice
//   'public:type'     (state: TSlice, data: z.output of publicEvents[type], meta: PublicEventMeta) => TSlice
//   'channel:type'    (state: TSlice, data: z.output of channels[type],     meta: PublicEventMeta) => TSlice
//   'group:deletion'  (state: TSlice, data: GroupDeletionData,              meta: GroupDeletionMeta) => TSlice
type SliceReducers<TSlice, T extends AppTypes>

// A group event its author or the group's admin deleted: hide (senderDid, eventId)
interface GroupDeletionData {
  groupDid: string
  seq: number          // the deleted event's seq in the group
  senderDid: string
  eventId: string
  deletedBy: string    // its author, or the admin at the time
  noticeSeq: number    // the deletion notice's own seq
}

interface GroupDeletionMeta {
  groupDid: string
  senderDid: string    // who deleted it
}

interface AppTypes<TEvents, TPublicEvents, TChannels, TState> {
  events: TEvents
  publicEvents: TPublicEvents
  channels: TChannels
  state: TState
}

// Get an app's AppTypes from its definition
type App = typeof app extends DecentrlApp<infer T> ? T : never

const client = app.createClient({
  mediatorDid: 'did:web:mediator.decentrl.io',
  persist: { key: 'myapp', appVersion: '1' },   // optional localStorage persistence (identity, contract keys, state)
  transport: customTransport,                   // optional custom transport
})

interface DecentrlClientConfig {
  mediatorDid?: string
  persist?: PersistOptions
  transport?: DecentrlTransport
}

interface PersistOptions {
  key: string          // localStorage key prefix
  appVersion?: string  // bump when reducers change meaning: older snapshots are discarded
}

client.publish<K extends EventName<App>>(
  eventType: K,
  data: EventInput<App, K>,
  options?: PublishOptions,
): Promise<{ eventId: string }>

interface PublishOptions {
  recipient?: string
  ephemeral?: boolean
  eventId?: string   // reuse the ID of a failed publish to retry it; a random UUID when omitted
}

client.publishPublic<K extends PublicEventName<App>>(
  eventType: K,
  data: PublicEventInput<App, K>,
  options?: PublicPublishOptions,
): Promise<{ publicEventId: string; eventId: string }>
client.deletePublicEvent(publicEventId: string, eventType?: string): Promise<void>
client.queryPublicEvents(options: PublicQueryOptions): Promise<VerifiedPublicEvents<PublicEventOf<App>>>
client.readPublicState(
  publisherDid: string,
  options?: { tags?: string[]; mediatorEndpoint?: string },
): Promise<StateOf<App>>
client.subscribeToChannel(config: ChannelSubscriptionConfig): { unsubscribe: () => void }
client.onPublicEvent(listener: (envelope: PublicEventOf<App>) => void): () => void

interface PublicQueryOptions {
  publisherDid: string
  mediatorEndpoint?: string
  tags?: string[]
  afterTimestamp?: number    // unix ms, as signed by the publisher
  beforeTimestamp?: number   // unix ms
  pagination?: { page: number; pageSize: number }
}

interface VerifiedPublicEvents<TEnvelope> {
  data: TEnvelope[]          // verified envelopes, newest first
  pagination: PaginationMeta // the mediator's paging, dropped events included
  dropped: DropCounts
}

type DropCounts = Record<'forged' | 'unverifiable' | 'unknownType' | 'invalid' | 'malformed', number>

interface PublicPublishOptions {
  eventId?: string   // reuse to retry; the mediator returns the existing post
}

client.getState(): StateOf<App>
client.subscribe(listener: (state: StateOf<App>) => void): () => void

client.query(options?: QueryOptions): Promise<PaginatedResult<EventOf<App>>>
client.queryAndProcess(options?: QueryOptions): Promise<{ processed: number; total: number }>
client.onEvent(listener: (envelope: EventOf<App>) => void): () => void

interface QueryOptions {
  tags?: string[]
  participantDid?: string
  afterTimestamp?: number    // unix ms: when the own mediator stored the event
  beforeTimestamp?: number   // unix ms
  pagination?: { page: number; pageSize: number }
}

client.startSync(options?: SyncOptions): void
client.stopSync(): void
client.sync(): Promise<void>
client.getConnectionStatus(): ConnectionStatus
client.onConnectionStatusChange(listener: (status) => void): () => void

interface SyncOptions {
  intervalMs?: number
  fallbackIntervalMs?: number
  onError?: (error: unknown) => void
  websocket?: boolean
}

type ConnectionStatus = 'disconnected' | 'connecting' | 'authenticating' | 'connected'

client.reset(): void

client.identity.getIdentity(): IdentityState | null
client.identity.requireIdentity(): IdentityState
client.identity.create({ alias, mediatorDid }): Promise<IdentityState>
client.identity.load(serialized: SerializedIdentity): IdentityState
client.identity.serialize(): SerializedIdentity
client.identity.reset(): void
client.identity.onChange(listener): () => void

client.contracts.request(recipientDid): Promise<void>
client.contracts.getPending(): Promise<PendingContractRequest[]>   // group invitations left out
client.contracts.accept(pendingId, encryptedPayload, ephemeralPubKey): Promise<void>
client.contracts.decline(pendingId): Promise<void>
client.contracts.revoke(participantDid): Promise<void>
client.contracts.refresh(): Promise<void>
client.contracts.getActiveContracts(): StoredSignedContract[]   // status 'active' only
client.contracts.getUnkeyedContracts(): StoredSignedContract[]  // no keys on this device
client.contracts.getContractByDid(did): StoredSignedContract | undefined
client.contracts.onChange(listener): () => void

client.groups.isSupported: boolean
client.groups.getGroups(): GroupSummary[]             // as last read; stable until they change
client.groups.onChange(listener: () => void): () => void
client.groups.refresh(): Promise<GroupSummary[]>

// Joining
client.groups.invitations(): Promise<GroupInvitationSummary[]>
client.groups.acceptInvitation(pendingId): Promise<void>
client.groups.declineInvitation(pendingId): Promise<void>
client.groups.create(options: CreateGroupOptions): Promise<{ groupDid: string }>
client.groups.requestToJoin(groupDid, options?: { note?: string }): Promise<void>
client.groups.cancelJoinRequest(groupDid): Promise<void>
client.groups.leave(groupDid): Promise<void>
client.groups.view(groupDid): Promise<GroupView>

// Events
client.groups.publish<K extends EventName<App>>(
  groupDid: string,
  eventType: K,
  data: EventInput<App, K>,
  options?: { eventId?: string },
): Promise<{ eventId: string; seq: number }>
client.groups.delete(groupDid, event: EventOf<App> | GroupEventRef): Promise<void>
client.groups.read(groupDid, options?: GroupReadOptions): Promise<GroupEventsPage<App>>
client.groups.onDeletion(listener: (deletion: GroupDeletionData) => void): () => void
client.groups.counts(groupDid, queries: GroupCountQuery[]): Promise<Record<string, number>>
client.groups.online(groupDid): Promise<string[]>
client.groups.caughtUp(groupDid): Promise<void>

// Admin and staff
client.groups.invite(groupDid, did): Promise<void>
client.groups.pendingJoinRequests(groupDid): Promise<GroupJoinRequestSummary[]>   // admin or approvers
client.groups.approve(groupDid, pendingId): Promise<void>
client.groups.decline(groupDid, pendingId): Promise<void>
client.groups.remove(groupDid, did): Promise<void>    // the admin: rotates at once; staff: at its next upkeep
client.groups.staff(groupDid): Promise<GroupStaff>
client.groups.setGrant(groupDid, did, plan: StaffGrantPlan): Promise<void>   // the admin only
client.groups.revokeGrant(groupDid, did): Promise<void>
client.groups.vouch(groupDid, did): Promise<void>   // the admin only (v0.6)
client.groups.rotate(groupDid): Promise<void>
client.groups.handOver(groupDid, did): Promise<void>
client.groups.acceptHandover(groupDid): Promise<void>
client.groups.deleteGroup(groupDid): Promise<void>

interface GroupStaff {
  adminDid: string
  incomingAdminDid?: string     // named by a pending handover: staff too until it ends
  members: GroupStaffMember[]   // { did, capabilities: GrantCapabilities, deletePrefixes? }
  log: GroupStaffAction[]       // { seq, actorDid, action: 'approve' | 'decline' | 'remove', targetDid }
  unaccounted?: string[]        // the admin's device only (v0.6): members it cannot account for, who get no new keys
}

// Whether a viewer may delete an event, as the mediator will judge it (author, admin, or a grantee whose delete covers it; never staff's events)
canDeleteGroupEvent({ staff, viewerDid, authorDid, groupTags }): boolean

interface CreateGroupOptions {
  alias: string
  history?: 'from_join' | 'full'   // fixed for good: 'full' lets members added later read from the start
  mediatorDid?: string             // where the group lives; the identity's own mediator by default
}

// A group this identity is in, or asked to join
interface GroupSummary {
  groupDid: string
  alias: string                     // from the group's DID
  role: 'admin' | 'member'          // admin when this device administers it
  status: 'joined' | 'requested'
  keyed: boolean                    // a key is held: it can be read and posted to
  handoverOffered: boolean          // the admin offered to hand it over to this identity
}

interface GroupInvitationSummary {
  pendingId: string
  groupDid: string
  adminDid: string
}

interface GroupJoinRequestSummary {
  pendingId: string
  requesterDid: string
  note?: string          // absent without a note, or when this member cannot open it
  hasNote: boolean
  createdAt: string      // when the request reached the mediator, ISO 8601
}

interface GroupCountQuery {
  id: string             // the count's key in the answer, 1 to 56 characters
  tag?: string           // a group tag, counted as a prefix
  senderDid?: string
  afterSeq?: number
}

interface GroupReadOptions {
  tags?: string[]                        // any of these group tags; without, newest first
  direction?: 'forward' | 'backward'     // with tags; forward by default
  cursor?: GroupReadCursor               // where the previous page stopped
  limit?: number
}

type GroupEventsPage<App> =
  | { status: 'ok'; events: EventOf<App>[]; deletions: GroupDeletion[]; cursor: GroupReadCursor; hasMore: boolean }
  | { status: 'removed' | 'deleted' }

// Where a group event sits, with its id. A deletion without the id reaches no reducer
type GroupEventRef = { seq: number; senderDid: string; eventId: string; groupTags?: string[] }

interface GroupTransport {
  list(): Promise<GroupSummary[]>
  onChange(listener: () => void): () => void   // joins, key arrivals, role changes, removal
  invitations(): Promise<GroupInvitationSummary[]>
  acceptInvitation(pendingId: string): Promise<void>
  declineInvitation(pendingId: string): Promise<void>
  create(options: CreateGroupOptions): Promise<{ groupDid: string }>
  requestToJoin(groupDid: string, options?: { note?: string }): Promise<void>
  cancelJoinRequest(groupDid: string): Promise<void>
  leave(groupDid: string): Promise<void>

  publish(groupDid: string, envelope: EventEnvelope, options?: { groupTags?: string[] }): Promise<{ eventId: string; seq: number }>
  deleteEvent(groupDid: string, target: GroupTargetEvent): Promise<void>
  sync(groupDid: string, afterSeq: number): Promise<GroupSyncResult>   // an unkeyed group reads as empty
  readTagged(groupDid: string, options: GroupTaggedReadOptions): Promise<GroupPageResult>
  readBackward(groupDid: string, options?: GroupBackwardReadOptions): Promise<GroupPageResult>
  view(groupDid: string): Promise<GroupView>
  counts(groupDid: string, queries: GroupCountQuery[]): Promise<Record<string, number>>
  online(groupDid: string): Promise<string[]>

  invite(groupDid: string, did: string): Promise<void>
  pendingJoinRequests(groupDid: string): Promise<GroupJoinRequestSummary[]>
  approve(groupDid: string, pendingId: string): Promise<void>
  decline(groupDid: string, pendingId: string): Promise<void>
  remove(groupDid: string, did: string): Promise<void>
  staff(groupDid: string): Promise<GroupStaff>
  setGrant(groupDid: string, did: string, plan: StaffGrantPlan): Promise<void>
  vouch(groupDid: string, did: string): Promise<void>
  rotate(groupDid: string): Promise<void>
  handOver(groupDid: string, did: string): Promise<void>
  acceptHandover(groupDid: string): Promise<void>
  deleteGroup(groupDid: string): Promise<void>

  maintain(): Promise<void>                              // the admin's upkeep, throttled per group
  admitPending(): Promise<void>                          // key parcels for groups waiting to let this identity in
  watch(onHint: (hint: GroupHint) => void): () => void   // hints for the followed groups
}

// Where to look; best effort, syncing does not depend on hints
interface GroupHint {
  groupDid: string
  kind: 'events' | 'updated' | 'gone'
  seq?: number   // events up to this seq, when known
}

followedGroups(summaries: GroupSummary[]): string[]   // joined and keyed

createDirectGroups(options: DirectGroupsOptions): GroupTransport

interface DirectGroupsOptions {
  transport: DirectTransport
  store: GroupStore
  processPending: () => Promise<void>   // drains pending 1:1 events: a newer group key may be among them
  now?: () => number
}

const MAINTAIN_INTERVAL_MS = 60_000     // maintain() reconciles each admin group at most this often

interface GroupStore {
  readonly ready?: Promise<void>   // an async store's cache is loaded; control events wait for it
  loadMember(did: string): GroupMemberState
  loadAdmins(did: string): Record<string, SerializedGroupAdminInput>
  saveMember(did: string, state: GroupMemberState): void | Promise<void>
  saveAdmin(did: string, groupDid: string, state: SerializedGroupAdmin | null): void | Promise<void>
  withLock?<T>(name: string, fn: () => Promise<T>): Promise<T>   // admin work on one group, alone across tabs
  onExternalChange?(listener: (did: string) => void): () => void // another tab changed the member state
}

createMemoryGroupStore(): GroupStore
createLocalGroupStore(prefix: string, storage: Storage): GroupStore
mergeMemberState(stored: GroupMemberState, next: GroupMemberState): GroupMemberState
memberStorageKey(prefix, did)   // `${prefix}:groups:${did}`
adminStorageKey(prefix, did)    // `${prefix}:group-admins:${did}`

import { DirectTransport, GroupAdmin, GroupMember } from '@decentrl/sdk'

const transport = new DirectTransport()
await transport.createIdentity({ alias: 'alice', mediatorDid })

const member = new GroupMember({
  transport,
  state: savedMemberState,             // optional GroupMemberState; state from before v0.3 loads as joined
  onStateChanged: (state) => save(state),
  now: Date.now,                        // optional clock for join-request expiry, in ms
})

// Joining
member.acceptInvitation(request: PendingContractRequest): Promise<void>
member.requestToJoin(groupDid, options?: { note?: string }): Promise<void>
member.cancelJoinRequest(groupDid): Promise<void>
member.joinStatus(groupDid): 'joined' | 'requested' | undefined

// Posting and deleting
member.publish(groupDid, envelope: EventEnvelope, options?: { tags?: string[]; groupTags?: string[]; eventId?: string })
  : Promise<{ eventId: string; seq: number }>
member.deleteEvent(groupDid, target: GroupTargetEvent): Promise<void>
member.deleteOwnEvents(groupDid): Promise<number>   // how many were deleted

// Reading
member.sync(groupDid, afterSeq: number): Promise<GroupSyncResult>
member.readBackward(groupDid, options?: { cursor?: GroupReadCursor; limit?: number }): Promise<GroupPageResult>
member.readTagged(groupDid, options: {
  tags: string[]
  direction?: 'forward' | 'backward'
  cursor?: GroupReadCursor
  limit?: number
}): Promise<GroupPageResult>
member.watch(options: GroupWatchOptions): () => void   // returns a stop function

// The group
member.query(groupDid): Promise<GroupView>
member.leave(groupDid): Promise<void>
member.groups(): string[]                             // joined only, not requested
member.chain(groupDid): AdminLink[]                   // the verified admin chain held; empty before the first key
member.certificates(groupDid): GroupKeyCertificate[]
member.pendingHandovers(): Array<{ groupDid: string; adminEpoch: number }>
member.getState(): GroupMemberState

type GroupSyncResult =
  | { status: 'ok'; events: EventEnvelope[]; deletions: GroupDeletion[]; nextSeq: number; hasMore: boolean }
  | { status: 'removed' }     // NOT_A_GROUP_MEMBER
  | { status: 'deleted' }     // GROUP_DELETED or GROUP_NOT_FOUND

type GroupPageResult =
  | { status: 'ok'; events: EventEnvelope[]; deletions: GroupDeletion[]; cursor: GroupReadCursor; hasMore: boolean }
  | { status: 'removed' }
  | { status: 'deleted' }

// Where readTagged or readBackward continues: past (forward) or below (backward) seq;
// readTagged also resumes from key version `version`
interface GroupReadCursor {
  seq: number
  version?: number
}

// A deletion to apply: hide the event (senderDid, eventId)
interface GroupDeletion {
  seq: number          // the deleted event's seq
  senderDid: string
  eventId: string
  deletedBy: string    // its author, or the group's admin at the time
  noticeSeq: number    // the deletion notice's own seq
}

interface GroupTargetEvent {
  seq: number          // meta.groupSeq
  senderDid: string    // meta.senderDid
  eventId?: string     // meta.eventId; omit when you cannot read the event
  groupTags?: string[] // meta.groupTags: readers by those tags see the deletion too
}

interface GroupWatchOptions {
  groupDids: string[]
  cursors?: Record<string, number>   // where each group's reading starts; 0 when absent
  onEvents?: (groupDid: string, page: { events: EventEnvelope[]; deletions: GroupDeletion[] }) => void
  onUpdated?: (groupDid: string) => void   // membership, keys or admin changed
  onGone?: (groupDid: string, status: 'removed' | 'deleted') => void   // no longer watched
}

interface GroupView {
  adminDid: string
  chain: AdminLink[]
  adminFromSeqs: (number | null)[]   // per link, the seq it took effect at; null where not recorded
  pendingLink: AdminLink | null
  members: string[]
  keyVersion: number
  rotationDue: boolean
  history: 'from_join' | 'full'      // as the mediator reports it; the genesis link is what counts
}

GroupAdmin.create({ member, alias, mediatorDid, history?, onStateChanged?, now? }): Promise<GroupAdmin>
GroupAdmin.fromState(state: SerializedGroupAdminInput, { member, onStateChanged?, now? }): Promise<GroupAdmin>
GroupAdmin.acceptHandover({ groupDid, member, onStateChanged?, now? }): Promise<GroupAdmin>

admin.groupDid: string
admin.invite(did): Promise<void>
admin.setGrant(did, plan: StaffGrantPlan): Promise<void>
admin.revokeGrant(did): Promise<void>
admin.vouch(did): Promise<string[]>     // the members delivered to
admin.reconcile(): Promise<ReconcileSummary>
admin.rotate(): Promise<number>          // the new key version
admin.remove(did): Promise<number>       // removes and rotates in one step
admin.redeliverKeys(did, fromVersion?: number): Promise<string[]>   // the members delivered to
admin.handOver(did): Promise<void>
admin.delete(): Promise<void>
admin.getState(): SerializedGroupAdmin

interface ReconcileSummary {
  status: 'admin' | 'handed-over' | 'deleted'
  added: string[]
  rotatedTo?: number
  delivered: string[]
  revoked: string[]
  reinvited: string[]
  left: string[]
  expired: string[]     // invitations never accepted within 30 days, forgotten
  dismissed: number     // contract requests to the group that were not join requests
}

type GroupInvite = { did: string; at: number }   // SerializedGroupAdmin.invites; at is ms

transport.setReservedEventHandler(handler: ReservedEventHandler): void
transport.requestContract(recipientDid, options?: {
  signInvitation?: (contract) => GroupInvitation
  joinRequest?: { note?: string }   // never together with signInvitation
}): Promise<void>

interface EventMeta {
  senderDid: string   // authenticated
  timestamp: number   // unix ms, as claimed by the sender
  eventId: string     // authenticated: signed inside the envelope
  ephemeral?: boolean
  groupDid?: string   // authenticated; set on group events read from that group, never on 1:1 events
  groupSeq?: number   // group events: the event's seq on the group's mediator, what deleteEvent takes
  groupTags?: string[] // group events: the sender's signed group tags, when it set any
}

interface EventEnvelope<TType extends string = string, TData = unknown> {
  type: TType
  data: TData
  meta: EventMeta
  tags?: string[]
  _mediatorEventId?: string   // the stored row's ID on your mediator (not meta.eventId)
  _storedAt?: number          // when your mediator stored it (its clock, unix seconds)
}

interface PublicEventMeta {
  publisherDid: string
  timestamp: number        // unix ms, as signed by the publisher
  eventId: string          // the publisher's signed event ID
  publicEventId: string    // the mediator's ID for the post: what deletePublicEvent takes
}

interface PublicEventEnvelope<TType extends string = string, TData = unknown> {
  type: TType
  data: TData
  meta: PublicEventMeta
  tags?: string[]
}

// A public event as the mediator serves it: unverified, timestamp in unix seconds.
// The client verifies these into envelopes; you rarely see one.
interface PublicEventResult {
  id: string               // the mediator's ID for the post
  eventId: string | null   // the signed event ID; null only on posts from before event IDs
  event: string
  tags: string[]
  timestamp: number
  eventSignature: string
}

interface IdentityState {
  did: string
  alias: string
  mediatorDid: string
  mediatorEndpoint: string
  keys: DecentrlIdentityKeys
  mediatorContract: SignedCommunicationContract | null
}

interface SerializedIdentity {
  did: string
  alias: string
  mediatorDid: string
  mediatorEndpoint: string
  keys: { signing: SerializedKeyPair; encryption: SerializedKeyPair; storageKey: string }
  mediatorContract: SignedCommunicationContract | null
}

interface StoredSignedContract {
  id: string
  participantDid: string
  participantAlias?: string
  signedCommunicationContract: SignedCommunicationContract
  createdAt: number
  status: 'active' | 'unkeyed'   // unkeyed: this device holds no keys; request again to reconnect
}

interface PendingContractRequest {
  id: string
  senderDid: string
  encryptedPayload: string
  requestorEphemeralPublicKey: string
  groupInvitation?: { groupDid: string; adminDid: string }   // a verified group invitation
  joinRequest?: { note?: string }                              // someone asks to join the group this identity is
}

class DecentrlSDKError extends Error {
  code: DecentrlSDKErrorCode
  details?: unknown
}

type DecentrlSDKErrorCode =
  | 'IDENTITY_NOT_INITIALIZED'
  | 'IDENTITY_ALREADY_EXISTS'
  | 'CONTRACT_NOT_FOUND'
  | 'SCHEMA_VALIDATION_FAILED'
  | 'UNKNOWN_EVENT_TYPE'
  | 'SYNC_FAILED'
  | 'PUBLISH_FAILED'
  | 'QUERY_FAILED'
  | 'QUERY_NOT_SUPPORTED'
  | 'MEDIATOR_ERROR'
  | 'RECIPIENT_MEDIATOR_NOT_FOUND'
  | 'NO_TRANSPORT'
  | 'RESERVED_HANDLER_TOO_LATE'   // GroupMember attached after the transport's first sync
  | 'GROUP_UNKEYED'               // no key for the group yet
  | 'STALE_GROUP_KEY'             // a newer key is on its way; sync, then retry with details.eventId
  | 'GROUP_REMOVED'               // you are not a member (any more)
  | 'GROUP_DELETED'               // the group was deleted or is unknown to its mediator
  | 'GROUP_REFUSED'               // any other refusal; details.code has the mediator's code
  | 'NO_MATCHING_HANDOVER'        // no held handover matches the pending link
  | 'GROUP_HANDED_OVER'           // this device no longer administers the group
  | 'INVALID_GROUP_TAGS'          // more than 8 group tags on a post, or not 1 to 64 tags to read by
  | 'ALREADY_A_MEMBER'            // requestToJoin for a group already joined
  | 'KEYS_UNDELIVERED'            // handOver: keys owed to the successor could not be delivered
  | 'GROUPS_NOT_SUPPORTED'        // client.groups on a transport without groups