AtlasClient

public class AtlasClient

Central class for interacting for the Forsta Atlas server.

You’ll use this for Atlas authentication, user creation and manipulation, tag creation and manipulation, and tag-math evaluation to resolve message distributions.

It requires an object conforming to KVStorageProtocol so it can maintain login sessions across invocations, etc.

Attributes

delegates
The registered delegates for this Atlas client
Declaration
Swift

public let delegates: Delegates<AtlasClientDelegate>
Show on GitHub
defaultOrg
The default public organization name (added to unqualified login tags)
Declaration
Swift

public var defaultOrg: String? { get set }
Show on GitHub
serverUrl
The URL of the Atlas server we are using
Declaration
Swift

public var serverUrl: String? { get set }
Show on GitHub
authenticatedUserId
The current authenticated user UUID
Declaration
Swift

public var authenticatedUserId: UUID?
Show on GitHub
isAuthenticated
predicate for whether this Atlas client is currently authenticated
Declaration
Swift

public var isAuthenticated: Bool { get }
Show on GitHub
authenticatedUserJwt
The current authenticated user JWT (will be automatically set and maintained)
Declaration
Swift

public var authenticatedUserJwt: String? { get set }
Show on GitHub

Constructors


                    
                    
                    init(kvstore:)

Initialize this Atlas client. This will resume maintaining an auth session, if possible.

Declaration

Swift

public init(kvstore: KVStorageProtocol)

Parameters


                                kvstore

a persistent key-value store

Show on GitHub

Authentication and JWT Maintenance


                    
                    
                    requestAuthentication(_:)

Request a user’s authentication method for the Atlas server. (This will trigger the transmission of an SMS code if applicable.)

Declaration

Swift

public func requestAuthentication(_ userTag: String) -> Promise<AuthenticationMethod>

Parameters


                                userTag

Tag for the user to authenticate as. It takes the form [@]user[:org].

Return Value

A Promise that resolves to an AuthenticationMethod indicating how to complete authentiation.

Show on GitHub


                    
                    
                    authenticateViaCode(userTag:code:)

Authentication via SMS code

Declaration

Swift

public func authenticateViaCode(userTag: String, code: String) -> Promise<AuthenticatedUser>

Parameters

`userTag`	Tag for the user. It takes the form [@]user[:org].
`code`	SMS code that was sent to the user when `requestAuthentication` was called.

Return Value

A Promise that resolves to an AuthenticatedUser JSON blob for the user

Show on GitHub


                    
                    
                    authenticateViaPassword(userTag:password:)

Authentication via password

Declaration

Swift

public func authenticateViaPassword(userTag: String, password: String) -> Promise<AuthenticatedUser>

Parameters

`userTag`	Tag for the user. It takes the form [@]user[:org].
`password`	The user’s password.

Return Value

A Promise that resolves to an AuthenticatedUser JSON blob for the user

Show on GitHub


                    
                    
                    authenticateViaPasswordOtp(userTag:password:otp:)

Authentication via password + authenticator code

Declaration

Swift

public func authenticateViaPasswordOtp(userTag: String, password: String, otp: String) -> Promise<AuthenticatedUser>

Parameters

`userTag`	Tag for the user. It takes the form [@]user[:org].
`password`	The user’s password.

Return Value

A Promise that resolves to an AuthenticatedUser JSON blob for the user

Show on GitHub


                    
                    
                    authenticateViaUserAuthToken(token:)

Authentication via a UserAuthToken

Declaration

Swift

public func authenticateViaUserAuthToken(token: String) -> Promise<AuthenticatedUser>

Parameters


                                token

A UserAuthToken for the authenticating user.

Return Value

A Promise that resolves to an AuthenticatedUser JSON blob for the user

Show on GitHub


                    
                    
                    authenticateViaJwtProxy(jwt:)

Authentication via UserAuthToken

Declaration

Swift

public func authenticateViaJwtProxy(jwt: String) -> Promise<AuthenticatedUser>

Parameters

jwt

A JWT proxy for the authenticating user.

Return Value

A Promise that resolves to an AuthenticatedUser JSON blob for the user

Show on GitHub

Invitation, Conversation, User, and Org CRUD


                    
                    
                    createUser(_:)

Administrator creation of a new user in the same organization.

REQUIRED FIELDS: first_name, tag_slug

ALERT: if tag_slug is already taken in the caller’s org, the result will be a clunky 500 error

Declaration

Swift

public func createUser(_ fields: [String : Any]) -> Promise<JSON>

Parameters


                                fields

dictionary of optional and required fields for the new user

Return Value

A Promise that resolves to a JSON blob of the new user

Show on GitHub


                    
                    
                    updateUser(_:_:)

Administrator update of a new user in the same organization.

Declaration

Swift

public func updateUser(_ userId: UUID, _ patchFields: [String : Any]) -> Promise<JSON>

Parameters

`userId`	the user’s UUID
`patchFields`	dictionary of (only) the fields to update in the user

Return Value

A Promise that resolves to a JSON blob of the updated user

Show on GitHub


                    
                    
                    createUserAuthToken(userId:description:)

Request creation of a UserAuthToken

Declaration

Swift

public func createUserAuthToken(userId: UUID? = nil, description: String? = nil) -> Promise<(UUID, String)>

Parameters

`userId`	optional user ID to create the token for a user other than self (requires being an org admin)
`description`	optional description for this token

Return Value

A Promise that resolves to a tuple of the token’s ID and the UserAuthToken

Show on GitHub


                    
                    
                    joinForsta(invitationToken:_:)

Unauthenticated creation of an account (and an org for it, optionally). On success, this also sets the JWT for this AtlasClient.

Required fields:

captcha: reCaptcha’s output
phone: The new user’s phone number
email: The new user’s email address
fullname: The new user’s full name
tag_slug: The new user’s usertag slug text
password: The new user’s password text

Optional fields (only define these if you are creating a new org):

org_name: Full name of the new org
org_slug: Slug text for the new org

Declaration

Swift

public func joinForsta(invitationToken: String? = nil,
                       _ fields: [String: Any]) -> Promise<(String, UUID)>

Parameters

`invitationToken`	Optional invitation token that was obtained from /v1/invitation
`fields`	dictionary of the fields to define the new user and possibly org

Return Value

A Promise that resolves to a tuple of the new user’s fully-qualified tag string and userId UUID: (tag, uuid)

Show on GitHub


                    
                    
                    sendInvitation(_:)

Generate an invitation from Atlas. Repeated invitations for the same person (currently identified via phone number) will return the same pending user ID.

Possible fields:

phone: The new user’s phone number (required)
email: The new user’s email address (optional)
first_name: The new user’s first name (optional)
last_name: The new user’s last name (optional)
message: Supplementary message for invitation (optional)

Declaration

Swift

public func sendInvitation(_ fields: [String : Any]) -> Promise<UUID>

Parameters


                                fields

dictionary of the fields giving informatino about the invited user

Return Value

a Promise that resolves to the UUID of the pending user who was sent an invitation

Show on GitHub


                    
                    
                    revokeInvitation(_:)

Revoke a pending invitation.

Declaration

Swift

public func revokeInvitation(_ pendingUserId: UUID) -> Promise<Void>

Parameters


                                pendingUserId

the user ID of the pending invited user

Return Value

a Promise that resolves upon completion of the task

Show on GitHub


                    
                    
                    getInvitationInfo(_:)

Get information about an invitation via its token. (This is intended to help clients present pre-filled forms for joining based on what Atlas has been given about them, perhaps accumulated across several invitation requests to Atlas.)

Declaration

Swift

public func getInvitationInfo(_ invitationToken: String) -> Promise<JSON>

Parameters


                                invitationToken

the token for the invitation

Return Value

a Promise that resolves to JSON containing accumulated field values for prefilling a form leading to a joinForsta()

Show on GitHub

ConversationInfo
Undocumented
See more
Declaration
Swift

public class ConversationInfo
Show on GitHub


                    
                    
                    createConversation(captcha:threadId:distribution:expires:)

Generate a Conversation.

Declaration

Swift

public func createConversation(captcha: String? = nil,
                               threadId: UUID? = nil,
                               distribution: String? = nil,
                               expires: Date? = nil) -> Promise<ConversationInfo>

Parameters

`captcha`	reCaptcha’s output, required if not currently signed in
`threadId`	optional thread id (defaults to a random uuid4)
`distribution`	optional starting distribution (defaults to empty, or self if signed in)
`expires`	optional expiration datetime (defaults to 1 day from now)

Return Value

a Promise that resolves to a ConversationInfo

Show on GitHub


                    
                    
                    getConversationInfo(_:)

Get information about a Conversation (if the requesting user is its creator)

Declaration

Swift

public func getConversationInfo(_ conversationToken: String) -> Promise<ConversationInfo>

Parameters


                                conversationToken

An existing Conversation’s token

Return Value

a Promise that resolves to a ConversationInfo

Show on GitHub


                    
                    
                    joinConversation(_:firstName:lastName:email:phone:)

Join a Conversation. If not authenticated with Atlas, this will cause an ephemeral user to be created and this AtlasClient will begin maintaining a JWT for it.

Declaration

Swift

public func joinConversation(_ conversationToken: String,
                             firstName: String? = nil,
                             lastName: String? = nil,
                             email: String? = nil,
                             phone: String? = nil) -> Promise<ConversationInfo>

Parameters

`conversationToken`	An existing Conversation’s token
`firstName`	optional first name (used if an ephemeral user is created, defaults to Anonymous)
`lastName`	optional last name (used if an ephemeral user is created)
`email`	optional email (used if an ephemeral user is created)
`phone`	optional phone (used if an ephemeral user is created)

Return Value

a Promise that resolves to a ConversationInfo

Show on GitHub

Tag and User Directory Services


                    
                    
                    resolveTagExpressions(_:)

Takes an array of tag expressions (i.e @foo + @bar - (@joe + @sarah)) and resolves them to their current user memberships.

Declaration

Swift

public func resolveTagExpressions(_ expressions: [String]) -> Promise<[TagExpressionResolution]>

Parameters


                                expressions

an array of String tag expressions

Return Value

a Promise resolving to a matching array of TagExpressionResolutions

Show on GitHub


                    
                    
                    getUsers(userIds:onlyPublicDirectory:)

Get user objects based on a list of user IDs. First try to get it from the (more verbose) /user endpoint for users in the same org, then fall back to the (more lightweight) /directory/user public directory for those in other orgs.

Declaration

Swift

public func getUsers(userIds: [UUID], onlyPublicDirectory: Bool = false) -> Promise<[JSON]>

Parameters

`userIds`	Array of user ID `UUID`s to look up.
`onlyPublicDirectory`	Optional boolean to only use the Forsta public directory. E.g. only return lightweight user objects.

Return Value

A Promise resolving to a JSON array of the users’ information

Show on GitHub


                    
                    
                    getUsers(q:)

Get all user objects in this org based on an optional search/filter query string. Retrieves from the /v1/user endpoint. This will retrieve all pages of results.

Declaration

Swift

public func getUsers(q: String? = nil) -> Promise<[JSON]>

Parameters

`q`	Optional query search/filter string. No query string means retreive all users.

Return Value

A Promise resolving to a JSON array of retrieved users’ information

Show on GitHub

getTags()
Get all tag objects for this org. Retrieves from the /v1/tag endpoint. This will retrieve all pages of results.
Declaration
Swift

public func getTags() -> Promise<[JSON]>
Return Value

A Promise resolving to a JSON array of retrieved tags’ information

Show on GitHub

Atlas Calls for Signal Server Assistance


                    
                    
                    provisionSignalDevice(uuidString:pubKeyString:)

Request provisioning assistance from any existing devices.

Declaration

Swift

public func provisionSignalDevice(uuidString: String, pubKeyString: String) -> Promise<JSON>

Parameters

`uuidString`	provisioning UUID string provided by Signal server
`pubKeyString`	base64-encoded public key to use in encrypting provisioning secrets for me

Return Value

Promise resolving to results bundled in a JSON

Show on GitHub

provisionSignalAccount(_:)
Provision/refresh a new Signal Server account.
Declaration
Swift

public func provisionSignalAccount(_ fields: [String : Any]) -> Promise<JSON>
Return Value

Promise resolving to results bundled in a JSON.

Show on GitHub
getSignalAccountInfo()
Retrieve information about the current Signal server account and its devices.
Declaration
Swift

public func getSignalAccountInfo() -> Promise<SignalAccountInfo>
Show on GitHub
getRtcTurnServersInfo()
Retrieve information about our WebRTC TURN servers.
Declaration
Swift

public func getRtcTurnServersInfo() -> Promise<[JSON]>
Return Value

Promise resolving to an array of JSON with TURN server info.

Show on GitHub

Utilities


                    
                    
                    tagParts(_:)

Breaks a tag into (normalized) user and org slug parts.

Declaration

Swift

public func tagParts(_ tag: String) -> (String, String)

Parameters

tag

a string shaped like [@]user[:org]

Return Value

a tuple of (user, org) slug Strings – trimmed, lowercased, @-stripped (also, a missing org will default to self.defaultOrg)

Show on GitHub

Related Subtypes

AuthenticationMethod
A user’s current method of interactive authentication
See more
Declaration
Swift

public enum AuthenticationMethod
Show on GitHub
AuthenticatedUser
The JSON blob detailing an authenticated user on Atlas
Declaration
Swift

public typealias AuthenticatedUser = JSON
Show on GitHub
SignalAccountInfo
Account info reported by Signal server
See more
Declaration
Swift

public struct SignalAccountInfo
Show on GitHub
TagExpressionResolution
Results of evaluating a tag expression
See more
Declaration
Swift

public struct TagExpressionResolution
Show on GitHub