@hearro/hearro-sdk 0.0.3

@hearro/hearro-sdk

0.0.3

hearro ▸
User
Invite
Connection
Conversation
ConversationItem
Entity
Image
Link
Name
ConversationMessage
RTCSession

Need help reading this?

hearro

HearRo SDK

Abstraction for interacting with the HearRo API.

The SDK will manage the GraphQL client and handle packing/unpacking DidComm messages where appropriate.

Almost All functions return promises that can be async/awaited to recieve the results of the function.

Most API interaction with HearRo is via DidComm messages with the User's agent. All HearRo users have a static connection to their cloud agent, and the keys for interacting with this agent are provided in their embeded wallet. This wallet is never sent over the wire unencrypted - once they log in, the wallet must be opened (decrypted) locally. At this point the user will be able to interact with their cloud agent, who is responsible for managing their cloud wallet and all their conections to HearRo resources.

new hearro(options: Object)

Parameters

options (Object) SDK Configuration Options

Name	Description
options.api `Object`	API Access options
options.api.httpEndpoint `String`	HTTP Endpoint
options.orgId `String`	HearRo Organization DID

Instance Members

▸ login(options)

Logs in a user

This is the first of two steps required to send messgaes to the user's HearRo agent. After you log in a user, you must call open wallet to decrypt the local wallet

Parameters

options (Object)

Name	Description
options.email `String`	user's email address
options.password `String`	user's password

Returns

Promise<(User | Error)>: promise to the user's data

▸ loggedInUser()

Returns the currently logged in user.

If there is no user data an empty object will be returned

loggedInUser(): User

Returns

User: Currently logged in user

▸ logOutUser()

Log's out the user.

Closes their wallet and removes stored user data

logOutUser()

▸ createUser(options)

Creates a HearRo user

createUser(options: Object): Promise<(User | Error)>

Parameters

options (Object)

Name	Description
options.email `String`	user's email address
options.password `String`	password for the user
options.first `String`	user's real first name
options.last `String`	user's real last name

Returns

Promise<(User | Error)>: promise to the user data if successfully created

▸ openWallet(options)

Open the user's embedded wallet

Must be called after login - this uses the provided password to generate an unlock key for the emeded wallet.

openWallet(options: Object): Promise<(User | Error)>

Parameters

options (Object)

Name	Description
options.password `String`	User's password

Returns

Promise<(User | Error)>: decrypts the user's wallet. Promise will resolve when finished

▸ closeWallet()

closes the user's wallet

closeWallet(): Promise<Null>

Returns

Promise<Null>: resolves once the user's wallet is closed

▸ myAgentKey(publicKey)

check if the provided key represents the static connection to my agent

myAgentKey(publicKey: String): Promise<Boolean>

Parameters

publicKey (String) a public key base58 string

Returns

Promise<Boolean>: true if the key is my agent's

▸ emailExists(email)

Checks if the provided email exists as a HearRo user

emailExists(email: String): Promise<(User | Error)>

Parameters

email (String) email address to check

Returns

Promise<(User | Error)>: basic user information

▸ sendInvite(options)

Invite a user to connect

sendInvite(options: Object): Promise<(Null | Error)>

Parameters

options (Object)

Name	Description
options.invitee `String`	email address to invite

Returns

Promise<(Null | Error)>: resolves when the invite was sent

▸ acceptInvite(options)

Accept an existing invite

acceptInvite(options: Object): Promise<(Null | Error)>

Parameters

options (Object)

Name	Description
options.id `String`	id of the invite to accept

Returns

Promise<(Null | Error)>: resolves if the invite was sucessfully accepted.

▸ invites()

Get any pending invites

invites(): Promise<(Array<Invite> | Error)>

Returns

Promise<(Array<Invite> | Error)>: array of oustanding invites

▸ connections()

Get user's connections

connections(): Promise<(Array<Connection> | Error)>

Returns

Promise<(Array<Connection> | Error)>: array of connections

▸ conversations()

Get user's conversations

conversations(): Promise<(Array<Conversation> | Error)>

Returns

Promise<(Array<Conversation> | Error)>: array of conversations

▸ conversationParticipants(id)

Get a list of the conversation participants

conversationParticipants(id: String): Promise<(Array<Entity> | Error)>

Parameters

id (String) conversation id

Returns

Promise<(Array<Entity> | Error)>: array of HearRo entities that are part of the conversation

▸ addConversationParticipant(options)

Add a participant to the conversation

This will add a participant that the user is already connected with (see hearro#connections)

addConversationParticipant(options: Object): Promise<(Null | Error)>

Parameters

options (Object)

Name	Description
options.conversationId `String`	conversation to add the participant to
options.participantDid `(String \| undefined)`	peer did of an existing connection to add
options.participantEmail `(String \| undefined)`	email of an existing connection to add

Returns

Promise<(Null | Error)>: resolves if the participant was sucessfully added

▸ sendConversationInvite(options)

Invite a user to a conversation

This sends a conversation invite to the user's email. At the moment this is scoped to the organization that is accessing the API. The invite will show up in the user's invite list

sendConversationInvite(options: Object): Promise<(Null | Error)>

Parameters

options (Object)

Name	Description
options.invitee `String`	email address to invite
options.message `String`	message to send with the invite
options.conversationId `any`

Returns

Promise<(Null | Error)>: resolves when the invite was sent

▸ acceptConversationInvite(options)

Accept a conversation invitation

acceptConversationInvite(options: Object): Promise<(Null | Error)>

Parameters

options (Object)

Name	Description
options.id `String`	ID of the invite to accept

Returns

Promise<(Null | Error)>: resolves when the invite was accepted

▸ conversationInvites()

Get any pending conversation invites

conversationInvites(): Promise<(Array<Invite> | Error)>

Returns

Promise<(Array<Invite> | Error)>: array of oustanding invites

▸ conversationMessage(options)

Send a message to a conversation

conversationMessage(options: Object): Promise<(Null | Error)>

Parameters

options (Object)

Name	Description
options.conversationId `String`	id of the conversation to send the message to
options.body `String`	body of the message
options.recipients `(Array<String> \| Null)`	array of recipients to send the message to. If empty message will go to all conversation recipeints.

Returns

Promise<(Null | Error)>: resolves if the message was successful

▸ loadConversationMessages(options)

Load existing Convesation Messages

loadConversationMessages(options: Object): Promise<(Array<ConversationMessage> | Error)>

Parameters

options (Object)

Name	Description
options.conversationId `String`	id of the conversation to load messages from
options.page `Number`	page to load
options.pageSize `Number`	message page size

Returns

Promise<(Array<ConversationMessage> | Error)>: array of conversation messages

▸ subscribeConversationMessages(options)

Subscribe to conversation messages

This function will return a susbscription to the conversation message stream

subscribeConversationMessages(options: Object): Promise<(CovnersationSubscription | Error)>

Parameters

options (Object)

Name	Description
options.conversationId `String`	id of the conversation to subscribe to

Returns

Promise<(CovnersationSubscription | Error)>: subscription to conversation message stream

Example

var cMessages = hearrosdk.subscribeConversationMessages({ conversationId: foo })
cMessages.subscribe({
  next({ message }) {
   console.log("messge received", message)
  },
  error (err) {
   console.log("error with the subscription", err.message)
  }
})

▸ newConversation(label, participants)

Create a new conversation

newConversation(label: String, participants: Array<String>)

Parameters

label (String) add a user friendly label to the conversation meta

participants (Array<String>) list of initial participants to add. These are the connectionIds of existing connections retreived from connections

▸ conversationItems(options)

Get a list of items in conversation

This call omits the data field in the ConversationItem. To download the conversation item use loadConversationItemData

conversationItems(options: Object): Promise<(Array<ConversationItem> | Error)>

Parameters

options (Object)

Name	Description
options.conversationId `String`	id of the conversation to load items from
options.page `Number`	page to load
options.pageSize `Number`	message page size

Returns

Promise<(Array<ConversationItem> | Error)>: array of conversation items

▸ createConversationItem(options)

Create a new conversation item

This is step one of two for uploading data to a conversation. It provisions the item and returns an item id that can be used to push the data to the conversation.

createConversationItem(options: Object)

Parameters

options (Object)

Name	Description
options.conversationId `String`	id of the conversation
options.name `String`	name of the item
options.size `Number`	item size in bytes
options.mimeType `String`	mime type of the item

▸ loadConversationItemData(options)

Download the actual conversation item data

This will return the ConversatioItem with the data field popluated.

loadConversationItemData(options: Object)

Parameters

options (Object)

Name	Description
options.conversationId `String`	id of the conversation
options.itemId `String`	id of the item

▸ saveConversationItemData(options)

Save conversation item data

This allows you to upload data for a previously created item. This uses the FileReader api to read binary data from the provided file param. This binary data is base64 encoded before being sent over the wire to the conversation

saveConversationItemData(options: Object)

Parameters

options (Object)

Name	Description
options.conversationId `String`	id of the conversation
options.itemId `String`	id of the item
options.file `File`	file object representing the data

▸ deleteConversationItem(options)

Delete conversation item

This will remove an item from the conversation and cannot be undone

deleteConversationItem(options: Object)

Parameters

options (Object)

Name	Description
options.conversationId `String`	id of the conversation
options.itemId `String`	id of the item

▸ getRTCSession(options)

Get RTC Session details

Returns detailed information about an RTC Session

getRTCSession(options: Object): Promise<(RTCSession | Error)>

Parameters

options (Object)

Name	Description
options.conversationId `String`	id of the conversation to load messages from
options.pageSize `String`	id of the session
options.sessionId `any`

Returns

Promise<(RTCSession | Error)>: rec session information

User

Type: Object

Properties

user (Object) : HearRo user data

user.id String
HearRo DID
user.email String
email address
user.name (Name | null)
user's real name

diddoc ((Object | null)) : peer DID Document representing the user's static connection to the agent

walletOpen (Boolean) : whether the user's wallet is open

Invite

Type: Object

Properties

id (String) : invite id

meta (Object) : invite meta data

Connection

Type: Object

Properties

doc (Object) : Did Doc

entity (Entity) : HearRo entity data for this connection

meta (Object) : meta data for this connection

Conversation

Type: Object

Properties

data (Object) : Diddoc for the conversation

meta (Object) : metadata for the conversation

ConversationItem

Type: Object

Properties

owner_id (String) : conversation participant that owns the item

id (String) : id of the item in the conversation. While universally unique, only accessible in the context of the conversation.

conversation_id (String) : id of the conversation this item belongs to

name (String) : name of the item

mime_type (String) : mime type of the item (e.g. "application/pdf")

size (Number) : size of the item

status (Number) : status of the item (Created, Error, Completed)

data (String) : base64 encoded raw data for the item

meta (Object) : additional optional metadata for this object

Entity

Type: Object

Properties

name (Name) : entity name

description (String) : entity description

image (Array<Image>) : images for the entity

link (Array<Link>) : links to data for this entity

parent (String) : if the entity has a parent

Image

Type: Object

Properties

location (String) : url for the image

type (String) : type of image (e.g. "avatar")

Link

Type: Object

Properties

name (String) : data name

description (String) : description of the data

location (String) : url for the data

type (String) : mimetype (e.g. "application/pdf")

Name

Type: Object

Properties

first ((String | undefined)) : first name

last ((String | undefined)) : last name

Label ((String | undefined)) : Label

ConversationMessage

Type: Object

Properties

body (String) : message body

conversation_id (String) : id of the conversation

mesasge_id (String) : id over the message

sender (String) : conversation Peer DID for the sender

timestamp (String) : RFC3339 timestamp when the sender sent the message

received (String) : RFC3339 timestemp when HearRo received the message

RTCSession

Type: Object

Properties

id (String) : rtc session did

conversation_id (String) : id of the conversation that owns this session

participants ((Array | undefined)) : list of allowed participants. If undefined all conversation participants may join

originator (String) : did of the participant that created the session

timestamp (String) : RFC3339 timestamp when the session was started

rtc_server (String) : HearRo rtc server responsible for this session

state (Number) : session state. Allowed values are: Active - 0; Locked - 1; Finished - 3; Archived - 4

null-null ((Array | undefined)) : list participants currently in the session