Documentation Github

Global

Members

string

# constant SCOPES

Enum of user account access roles than can be granted

View Source authUtils.js, line 9

Array.<string>

# constant allScopes

User account access roles that can be granted.

View Source authUtils.js, line 20

Array.<string>

# constant roles

User account access levels that can be requested.

View Source authUtils.js, line 42

Methods

# DestinationOAuthPopup(handle, preferredScope, tokenCatcherURLopt) → {Promise.<AuthResult>}

For a standalone destination without its own Immers Server, trigger OAuth flow to a user's home immer via popup window. Must be invoked from a trusted user input event handler to allow the popup.

Parameters:
Name Type Attributes Default Description
handle string

User's Immers Handle (username[home.immer] or username@home.immer)
preferredScope string

Level of access to request (remember the user can alter this before approving)
tokenCatcherURL string <optional>
 window.location

Redirect URI for OAuth, a page on your origin that runs catchToken on load

View Source authUtils.js, line 172

Promise.<AuthResult>

# ImmerOAuthPopup(localImmer, localImmerId, preferredScope, tokenCatcherURL, handleopt, deepLinkopt) → {Promise.<AuthResult>}

For complete immers, trigger popup window OAuth flow starting at local immer and redirecting as necessary. Must be invoked from a trusted user input event handler to allow the popup.

Parameters:
Name Type Attributes Description
localImmer string

Origin of the local Immers Server
localImmerId string

IRI of the local immer Place object
preferredScope string

Level of access to request (remember the user can alter this before approving)
tokenCatcherURL string

Redirect URI for OAuth, a page on your origin that runs catchToken on load
handle string <optional>

If known, you can provide the user's handle (username[home.immer]) to pre-fill login forms
deepLink 'Login' | 'Register' | 'Reset password' <optional>

Set the default tab to be shown on the login page

View Source authUtils.js, line 212

Promise.<AuthResult>

# catchToken() → {boolean|TokenResult}

Retrieve OAuth access token and authorization details from URL after redirect and pass it back to the opening window if in a pop-up. Returns true if a token was found and passed from popup to opener. Returns the token response data if a token was found but the window is not a popup (e.g. to pass on to ImmersClient.loginWithToken). Returns false if no token found.

View Source authUtils.js, line 60

boolean | TokenResult

# getURLPart(input, part)

Process a url-like input into a fully formed URL in order to fetch a specific portion via the URL API

Parameters:
Name Type Description
input string

potentially incomplete origin, e.g. domain/hostname, host, or origin
part string

property name from the URL API to return, e.g. 'origin' or 'host'

View Source utils.js, line 42

# htmlAnchorForPlace(place) → {string}

Generate anchor tag for a place, e.g. for arrive/leave summaries. Returned value is sanitized and safe to render.

Parameters:
Name Type Description
place Activities.APPlace

View Source utils.js, line 62

sanitized html

string

# oauthPopup() → {Promise.<AuthResult>}

Internal oauth popup handler

View Source authUtils.js, line 108

Promise.<AuthResult>

# parseHandle(handle) → {ParsedHandle}

Parse an immers handle string into username and home immer hostname

Parameters:
Name Type Description
handle string

Immers handle (username[home.immer] or username@home.immer)

View Source utils.js, line 14

Parsed handle object (values are undefined if handle not valid)

ParsedHandle

Type Definitions

object

# AuthResult

Properties:
Name Type Description
actor APActor

User's ActivityPub profile object
token string

OAuth access token
homeImmer string

User's home Immers Server origin
authorizedScopes Array.<string>

Scopes granted by user (may differ from requested scopes)
sessionInfo object

Any other params returned from the authorization server with the token

View Source authUtils.js, line 96

object

# Destination

Properties:
Name Type Attributes Description
name string

Title of the destination
url string

link to visit the destination
privacy string <optional>

'direct', 'friends', or 'public' determines who can view this Destination and url e.g. in recently visited places. Default: friends
description string <optional>

text summary of destination
previewImage string <optional>

thumbnail image url
immer Activities.APPlace <optional>

reference to the parent/homepage place object for this experience, if ommitted will use the local immer

View Source client.js, line 8

object

# FriendStatus

Properties:
Name Type Attributes Description
profile Profile

Profile object for friend
isOnline boolean

Currently online anywhere in Immers Space
locationName string <optional>

Name of current or last immer visited
locationURL string <optional>

URL of current or last immer visited
destination Destination <optional>

Destination object for current or last immer visited
status 'friend-online' | 'friend-offline' | 'request-receved' | 'request-sent' | 'none'

descriptor of the current relationship to this user
statusString string

Text description of current status, "Offline" / "Online at..."
__unsafeStatusHTML string

Unsanitized HTML description of current status with link. You must sanitize this string before inserting into the DOM to avoid XSS attacks.
statusHTML string

Sanitize HTML description of current status with link. Safe to insert into DOM.

View Source client.js, line 38

object

# ImmersClientNewMessageEvent

Properties:
Name Type Description
detail object
message Message

View Source client.js, line 68

object

# Message

Properties:
Name Type Attributes Description
id string

URL of original message activity object, usable as unique id
sender Profile

Message sender's Profile
timestamp Date

Message sent time
type string

Describes the message content: 'chat', 'media', 'status', or 'other'
__unsafeMessageHTML string

Unsanitized HTML message content. You must sanitize this string before inserting into the DOM to avoid XSS attacks.
messageHTML string

Sanitized HTML message content. Safe to insert into DOM. Media wrapped in IMG/VIDEO will have class immers-message-media
mediaType string <optional>

'image' or 'video' if the message is a media object
url string <optional>

source url if the message is a media object (messageHTML will contain appropriate tags to display the media, but url can be used if you need custom display)
destination Destination <optional>

location tied to the message, if available
_originalActivity object

the unmodified ActivityPub activity that is the source of the message

View Source client.js, line 52

Object

# ParsedHandle

Properties:
Name Type Description
username string | undefined

The user's local identifier
immer string | undefined

The user's home immer hostname

View Source utils.js, line 3

object

# Profile

Properties:
Name Type Description
id string

Globally unique identifier (ActivityPub IRI)
handle string

Shorthand globally unique identifier, format: username[home.immer]
displayName string

User's changeable preferred identifier, may contain spaces & symbols
homeImmer string

Domain of imme where user account is registered
username string

User's permanent uniqe identifier within their home immer
bio string

Text description of user, may contain sanitized HTML
avatarImage string

Profile icon url
avatarModel string

Profile avatar 3d model url
avatarObject Activities.APModel

Profile avatar full Model object
url string

Webpage to view full profile
collections object

Map of user collections - urls to fetch lists of related activities. May include user-generated collections in addition to those listed
avatars string

Activities with model objects representing user's collection of avatars
blocked string

User blocks
destinations string

Unique immers visited by user, most recent first
friends string

Most recent activity for each friend (see friendsList)
friendsDestinations string

Unique immers visited by user's friends, most recent first
inbox string

All incoming activities
outbox string

All outgoing activities

View Source client.js, line 17

object

# TokenResult

Properties:
Name Type Description
token string

OAuth access token
homeImmer string

User's home Immers Server origin
authorizedScopes Array.<string>

Scopes granted by user (may differ from requested scopes)
sessionInfo object

Any other params returned from the authorization server with the token

View Source authUtils.js, line 44

Events

object

# immers-client-blocked-update

Blocklist has changed

Properties:
Name Type Description
detail.blocked Array.<string>

Profile.id for each blocked user

View Source client.js, line 854

object

# immers-client-connected

User has connected to the immers server

Properties:
Name Type Description
detail.profile Profile

the connected user's profile

View Source client.js, line 373

# immers-client-disconnected

Fired when disconnected from immers server or logged out

View Source client.js, line 289

object

# immers-client-friends-update

Friends status/location has changed

Properties:
Name Type Description
detail.friends Array.<FriendStatus>

Current status for each friend

View Source client.js, line 839

ImmersClientNewMessageEvent

# immers-client-new-message

New chat or status message received

View Source client.js, line 874

object

# immers-client-profile-update

Profile data has changed

Properties:
Name Type Description
detail.profile Profile

updated profile

View Source client.js, line 888