Constructor

# new ImmersClient(destinationDescription, optionsopt)

Parameters:

Name	Type	Attributes	Description
`destinationDescription`	`Destination` \| `Activities.APPlace` \| `string`		Metadata about this destination used when sharing or url for the related Place object. Either a Destination/APPlace object or a url where one can be fetched.
`options`	`object`	<optional>
`localImmer`	`string`	<optional>	Domain (host) of the local Immers Server, if there is one
`allowStorage`	`boolean`	<optional>	Enable localStorage of handle & token for reconnection (make sure you've provided complaince notices as needed)

View Source client.js, line 82

Fires:

Classes

ImmersClient

Members

Type: Activities

# activities

Activities instance for access to low-level ActivityPub API

View Source client.js, line 88

Type: Array.<string>

# authorizedScopes

List of scopes authorized by the user during login. This may differ from what you requested, as the user can override during the authorization process.

See:

{SCOPES}

View Source client.js, line 935

Type: boolean

# connected

Is the client connected to the User's immer?

View Source client.js, line 106

Type: string

# handle

Users Immers handle, if known. May be available even when logged-out if passed via URL or stored from past login

View Source client.js, line 924

Type: Promise.<Activities.APPlace>

# localImmerPlaceObject

fetch the /o/immer object for the current immer from memory cache or network

View Source client.js, line 905

Type: Profile

# profile

User's Immers profile

View Source client.js, line 100

Type: Object.<string, any>

# sessionInfo

Additional data returned from the user's immer on login

Properties:

Name	Type	Attributes	Description
`isNewUser`	`boolean`	<optional>	true when this is the first login of a new local user
`email`	`string`	<optional>	only included on home immer domain when that immer has passEmailToHub config enabled and this is their first login
`provider`	`string`	<optional>	identity provider domain if on home immer domain and logged in with OpenId Connect and this is their first login

View Source client.js, line 115

Type: ImmersSocket

# streaming

ImmersSocket instance for access to low-level streaming API

View Source client.js, line 94

Methods

# addAvatar(sourceActivity) → {Promise.<string>}

Add an existing avatar to a user's personal avatar collection

Parameters:

Name	Type	Description
`sourceActivity`	`string` \| `Activities.APActivity`	Create activity for the avatar or IRI of activity (other activities with the avatar as their object, e.g. Offer, also allowed)

View Source client.js, line 616

Returns:

IRI of avatar add activity

Type: Promise.<string>

# async addFriend(handle)

This method will either initiate a new friend request or, if a request has already been received from the target user, accept a pending friend request. To create a friend connection, both users will need to call this method with the other user's handle.

Parameters:

Name	Type	Description
`handle`	`string`	the target user's immers handle or profile id

View Source client.js, line 536

# async blockList(forceRefresh) → {Promise.<Array.<string>>}

Fetch list of Profile.id of all users blocked by this user

Parameters:

Name	Type	Description
`forceRefresh`	`boolean`	skip local cache and fetch from server

View Source client.js, line 417

Returns:

Type: Promise.<Array.<string>>

# async blockUser(handle)

Add an someone to this immerser's blocklist. While on a blocklist, no messages/requests will sent or received between these two users, and any past messages will be omitted from feeds and friends lists. You should also prevent realtime interactions in your application from users in Profile.collections.blocked (e.g. hide avatars, mute audio)

Parameters:

Name	Type	Description
`handle`	`string`	the target user's immers handle or profile id

View Source client.js, line 577

# async connect(tokenCatcherURL, requestedRole, handleopt) → {string}

Connect to user's Immers Space profile, using pop-up window for OAuth if needed

Parameters:

Name	Type	Attributes	Description
`tokenCatcherURL`	`string`		Page on your domain that runs catchToken on load to retrieve the granted access token. Can be the same page as long as loading it again in a pop-up won't cause a the main session to disconnect.
`requestedRole`	`string`		Access level to request, see roles for details
`handle`	`string`	<optional>	User's immers handle. Optional if you have a local Immers Server

Deprecated:

Split into to methods, login and enter, for better control over when a user goes online

View Source client.js, line 1182

Returns:

token OAuth2 acess token

Type: string

# async corsProxyFetch(url, headers)

Attempt to fetch a cross-domain resource. Prefers using the local immer's proxy service if available, falling back to the user's home immer's proxy service if available or plain fetch.

Parameters:

Name	Type	Description
`url`	`string`	resource to GET
`headers`	`object`	fetch headers

View Source client.js, line 661

# createAvatar(name, glb, icon, privacy, toopt) → {Promise.<string>}

Upload a 3d model as an avatar and optionally share it

Parameters:

Name	Type	Attributes	Description
`name`	`string`		Name/description
`glb`	`Blob`		3d model gltf binary file
`icon`	`Blob`		Preview image for thumbnails
`privacy`	`string`		'direct', 'friends', or 'public'
`to`		<optional>	Addressees. Accepts Immers handles (username[domain.name]) and ActivityPub IRIs

View Source client.js, line 607

Returns:

IRI of avatar creation post

Type: Promise.<string>

# async deleteMessage(sourceActivity) → {Promise.<string>}

Delete a message.

Parameters:

Name	Type	Description
`sourceActivity`	`string` \| `Activities.APActivity`	IRI of activity or Activity in the Outbox

View Source client.js, line 446

Returns:

IRI of the remove activity

Type: Promise.<string>

# disconnect()

Disconnect from User's immer, retaining credentials to reconnect

View Source client.js, line 284

# async enter(destinationDescriptionopt)

Mark user as "online" at this immer and share the location with their friends. Must be called after successful login or restoreSession

Parameters:

Name	Type	Attributes	Description
`destinationDescription`	`Destination` \| `Activities.APPlace` \| `string`	<optional>

View Source client.js, line 228

# async exit()

Mark user as no longer online at this immer.

View Source client.js, line 268

# async feed() → {Promise.<Array.<Message>>}

Fetch a page of recent activity Messages

View Source client.js, line 402

Returns:

Type: Promise.<Array.<Message>>

# async friendsList() → {Promise.<Array.<FriendStatus>>}

Fetch list of friends and their online status and location

View Source client.js, line 386

Returns:

Type: Promise.<Array.<FriendStatus>>

# async getProfile(handle) → {Profile|undefined}

Get a user's profile object from their handle. Uses logged-in users's home immer proxy service if available

Parameters:

Name	Type	Description
`handle`	`string`	Immers handle

View Source client.js, line 729

Returns:

User profile or undefined if failed

Type: Profile | undefined

# handleImmerLinkClick(clickEvent)

Make navigating between immers easier by providing the user's handle to the next experience so they don't have to type it in. Use as an onClick handler to inject the "me hash" into any cross-origin anchor when navigating. Can be registered directly on the anchor or on a parent element. Will fallback to default click behavior if same-origin, not logged in, or unable to process url.

Parameters:

Name	Type	Description
`clickEvent`	`MouseEvent`

View Source client.js, line 802

Connect to user's Immers Space profile, using pop-up window for OAuth

Parameters:

Name	Type	Attributes	Description
`tokenCatcherURL`	`string`		Page on your domain that runs catchToken on load to retrieve the granted access token. Can be the same page as long as loading it again in a pop-up won't cause a the main session to disconnect.
`requestedRole`	`string`		Access level to request, see roles for details
`handle`	`string`	<optional>	User's immers handle. Optional if you have a local Immers Server
`registration`	`boolean`	<optional>	For use with local immer only, open the popup with the registration tab selected instead of login. handle will be used to prefill the registratoin form if provided

View Source client.js, line 176

Returns:

token OAuth2 acess token

Type: Promise.<string>

# loginWithToken(token, homeImmer, authorizedScopes, sessionInfoopt) → {Promise.<boolean>}

Initialize client with an existing credential, e.g. one obtained through a service account or one returned from catchToken when performing a redirect based OAuth flow

Parameters:

Name	Type	Attributes	Description
`token`	`string`		OAuth2 Access Token
`homeImmer`	`string`		Domain (host) for user's home immer
`authorizedScopes`	`string` \| `Array.<string>`		Scopes authorized for the token
`sessionInfo`	`object`	<optional>	optional session data provided alongside token

View Source client.js, line 200

Returns:

true if the login was successful

Type: Promise.<boolean>

# async logout(alsoLogoutFromImmeropt) → {Promise.<void>}

Disconnect from User's immer and delete any traces of user identity. If the user is from the local immer on the same apex domain (more info), alsoLogoutFromImmer can cause the login session on the immer to be terminated as well for a complete logout.

Parameters:

Name	Type	Attributes	Description
`alsoLogoutFromImmer`	`boolean`	<optional>	terminate the login session on the local immer as well

View Source client.js, line 305

Returns:

Type: Promise.<void>

# async move(destinationDescription)

Update user's current online location and share with friends

Parameters:

Name	Type	Description
`destinationDescription`	`Destination` \| `Activities.APPlace` \| `string`

View Source client.js, line 253

# navigateToImmerLink(href)

Navigate to a given url while injecting a "me hash" to provide the user's handle to the destination site so that they don't have to re-enter it. Safe to use without checking if user is logged in, will just navigate normally if not

Parameters:

Name	Type	Description
`href`	`string`

View Source client.js, line 825

# async reconnect() → {Promise.<boolean>}

Attempt to restore session from a previously granted token. Requires options.allowStorage

Deprecated:

Split into to methods, restoreSession and enter, for better control over when a user goes online

View Source client.js, line 1193

Returns:

Was reconnection successful

Type: Promise.<boolean>

# async removeAvatar(sourceActivity) → {Promise.<string>}

Remove user's avatar from their Avatar Collection.

Parameters:

Name	Type	Description
`sourceActivity`	`string` \| `Activities.APActivity`	Activity IRI or Activity from the Avatars Collection to remove

View Source client.js, line 649

Returns:

IRI of the remove activity

Type: Promise.<string>

# async removeFriend(handle)

Remove a relationship to another immerser, either by removing an existing friend, rejecting a pending incoming friend request, or canceling a pending outgoing friend request

Parameters:

Name	Type	Description
`handle`	`string`	the target user's immers handle or profile id

View Source client.js, line 552

# async resolveProfileIRI(handle) → {string|undefined}

Get a user ID/URL from their handle using webfinger

Parameters:

Name	Type	Description
`handle`	`string`	immers handle

View Source client.js, line 699

Returns:

The profile IRI or undefined if failed

Type: string | undefined

# async restoreSession() → {Promise.<boolean>}

Attempt to restore session from a previously granted token. Requires options.allowStorage

View Source client.js, line 211

Returns:

Was reconnection successful

Type: Promise.<boolean>

# sendChatMessage(content, privacy, toopt) → {Promise.<string>}

Send a message with text content. privacy level determines who receives and can acccess the message. direct: Only those named in to receive the message. friends: Direct plus friends list. public: Direct plus Friends plus accessible via URL for sharing.

Parameters:

Name	Type	Attributes	Description
`content`	`string`		The text/HTML content. Will be sanitized before sending
`privacy`	`string`		'direct', 'friends', or 'public'
`to`	`Array.<string>`	<optional>	Addressees. Accepts Immers handles (username[domain.name]) and ActivityPub IRIs

View Source client.js, line 437

Returns:

Url of newly posted message

Type: Promise.<string>

# async sendImage(image, privacy, toopt) → {Promise.<string>}

Upload and/or share an image. When image is a canvas element, its toBlob method is used to generate a png image to upload. When image is a File/Blob, it will be uploaded to the user's home immer and shared. The name attribute is optional, but type must contain the correct MIME. When image is a url, an existing image is shared without re-uploading. It's better to upload a file so that the user's home immer can ensure it remains available. privacy level determines who receives and can acccess the message. direct: Only those named in to receive the message. friends: Direct plus friends list. public: Direct plus Friends plus accessible via URL for sharing.

Parameters:

Name	Type	Attributes	Description
`image`	`File` \| `Blob` \| `HTMLCanvasElement` \| `string`		Image data to upload or url to share
`privacy`	`string`		'direct', 'friends', or 'public'
`to`	`Array.<string>`	<optional>	Addressees. Accepts Immers handles (username[domain.name]) and ActivityPub IRIs

View Source client.js, line 477

Returns:

Url of newly posted message

Type: Promise.<string>

# async sendModel(name, glb, iconopt, privacyopt, toopt)

Upload and optionally share a 3D model. GLB is preferred. Other single-file model formats can be uploaded, but may not be supported when shared to other immers. The blob's type attribute must contain the correct MIME.

The privacy and to arguments determine who receives and can access a post featuring the uploaded model. For some uses, like collecting a new avatar, you may omit these to not share a post (this user will still be able to see the model in their outbox). direct: Only those named in to receive the message. friends: Direct plus friends list. public: Direct plus Friends plus accessible via URL for sharing.

Parameters:

Name	Type	Attributes	Default	Description
`name`	`string`			Label for the model
`glb`	`File` \| `Blob`			the 3D model file
`icon`	`File` \| `Blob`	<optional>		optional 2d image preview for the model
`privacy`	`string`	<optional>	direct	'direct', 'friends', or 'public'
`to`	`Array.<string>`	<optional>		Addressees. Accepts Immers handles (username[domain.name]) and ActivityPub IRIs

View Source client.js, line 525

# sendVideo(video, privacy, toopt) → {Promise.<string>}

Upload and/or share a video. When video is a File/Blob, it will be uploaded to the user's home immer and shared. The name attribute is optional, but type must contain the correct MIME. When video is a url, an existing video is shared without re-uploading. It's better to upload a file so that the user's home immer can ensure it remains available.

Privacy level determines who receives and can access the message. direct: Only those named in to receive the message. friends: Direct plus friends list. public: Direct plus Friends plus accessible via URL for sharing.

Parameters:

Name	Type	Attributes	Description
`video`	`File` \| `Blob` \| `string`		Video data to upload or url to share
`privacy`	`string`		'direct', 'friends', or 'public'
`to`	`Array.<string>`	<optional>	Addressees. Accepts Immers handles (username[domain.name]) and ActivityPub IRIs

View Source client.js, line 503

Returns:

Url of newly posted message

Type: Promise.<string>

# async unblockUser(handle)

Remove someone to this immerser's blocklist. Messages will once again be sent & received between users and past messages from before the block will be visible again in feeds and friends lists.

Parameters:

Name	Type	Description
`handle`	`string`	the target user's immers handle or profile id

View Source client.js, line 588

# updateProfileInfo(info)

Update user's profile description

Parameters:

Name	Type	Attributes	Description
`info`	`object`
`displayName`	`string`	<optional>	User's preferred shorthand identifier, may contain spaces & symbols
`bio`	`string`	<optional>	Summary paragraph displayed on user profile

View Source client.js, line 323

# async useAvatar(avatar) → {Promise.<string>}

Update user's avatar in their profile.

Parameters:

Name	Type	Description
`avatar`	`object` \| `string`	Model type object or id for one (or activity containing the model as its object)

View Source client.js, line 625

Returns:

IRI of profile update activity

Type: Promise.<string>

# async waitUntilConnected() → {Promise.<true>}

Utility method to hide details for checking if user is logged in or waiting util they have before performing actions that require a logged-in user

View Source client.js, line 157

Returns:

Type: Promise.<true>

Example

await client.waitUntilConnected()
client.sendChatMessage('Hey friends, I am connected!', 'friends')

# static DestinationFromPlace(place) → {Destination}

Extract a Destination from a place object

Parameters:

Name	Type	Description
`place`	`Activities.APPlace`

View Source client.js, line 963

Returns:

Type: Destination

# static FriendStatusFromActivity(activity) → {FriendStatus}

Extract friend status information from their most recent location activity

Parameters:

Name	Type	Description
`activity`	`Activities.APActivity`

View Source client.js, line 984

Returns:

Type: FriendStatus

# static FriendsSorter(a, b)

Array.sort compareFunction to sort a friends list putting online friends at the top and the rest by most recent update

Parameters:

Name	Type	Description
`a`	`FriendStatus`
`b`	`FriendStatus`

View Source client.js, line 945

# static MessageFromActivity(activity) → {Message|null}

Extract a Message from an activity object

Parameters:

Name	Type	Description
`activity`	`Activities.APActivity`

View Source client.js, line 1038

Returns:

Type: Message | null

# static ProfileFromActor(actor) → {Profile}

Convert ActivityPub Actor format to Immers profile

Parameters:

Name	Type	Description
`actor`	`Activities.APActor`	ActivityPub Actor object

View Source client.js, line 1103

Returns:

Type: Profile

# static URLFromProperty(prop) → {string|undefined}

Links in ActivityPub objects can take a variety of forms. Find and return the URL string.

Parameters:

Name	Type	Description
`prop`	`Activities.APObject` \| `object` \| `string`

View Source client.js, line 1128

Returns:

URL string, if present

Type: string | undefined

immers-client Documentation

# new ImmersClient(destinationDescription, optionsopt)

Parameters:

Classes

Members

# activities

# authorizedScopes

# connected

# handle

# localImmerPlaceObject

# profile

# sessionInfo

Properties:

# streaming

Methods

# addAvatar(sourceActivity) → {Promise.<string>}

Parameters:

# async addFriend(handle)

Parameters:

# async blockList(forceRefresh) → {Promise.<Array.<string>>}

Parameters:

# async blockUser(handle)

Parameters:

# async connect(tokenCatcherURL, requestedRole, handleopt) → {string}

Parameters:

# async corsProxyFetch(url, headers)

Parameters:

# createAvatar(name, glb, icon, privacy, toopt) → {Promise.<string>}

Parameters:

# async deleteMessage(sourceActivity) → {Promise.<string>}

Parameters:

# disconnect()

# async enter(destinationDescriptionopt)

Parameters:

# async exit()

# async feed() → {Promise.<Array.<Message>>}

# async friendsList() → {Promise.<Array.<FriendStatus>>}

# async getProfile(handle) → {Profile|undefined}

Parameters:

# handleImmerLinkClick(clickEvent)

Parameters:

# async login(tokenCatcherURL, requestedRole, handleopt, registrationopt) → {Promise.<string>}

Parameters:

# loginWithToken(token, homeImmer, authorizedScopes, sessionInfoopt) → {Promise.<boolean>}

Parameters:

# async logout(alsoLogoutFromImmeropt) → {Promise.<void>}

Parameters:

# async move(destinationDescription)

Parameters:

# navigateToImmerLink(href)

Parameters:

# async reconnect() → {Promise.<boolean>}

# async removeAvatar(sourceActivity) → {Promise.<string>}

Parameters:

# async removeFriend(handle)

Parameters:

# async resolveProfileIRI(handle) → {string|undefined}

Parameters:

# async restoreSession() → {Promise.<boolean>}

# sendChatMessage(content, privacy, toopt) → {Promise.<string>}

Parameters:

# async sendImage(image, privacy, toopt) → {Promise.<string>}

Parameters:

# async sendModel(name, glb, iconopt, privacyopt, toopt)

Parameters:

# sendVideo(video, privacy, toopt) → {Promise.<string>}

Parameters:

# async unblockUser(handle)

Parameters:

# updateProfileInfo(info)

Parameters:

# async useAvatar(avatar) → {Promise.<string>}

Parameters:

# async waitUntilConnected() → {Promise.<true>}

Example

# static DestinationFromPlace(place) → {Destination}

Parameters:

# static FriendStatusFromActivity(activity) → {FriendStatus}

Parameters:

# static FriendsSorter(a, b)