Skip to content

Account

Jump to bottom
LaCivita, Jeremy edited this page May 26, 2022 · 8 revisions

Version The Firebolt JS Manage SDK [Alpha 4]

Overview

A module for managing Session.

OpenRPC

Firebolt APIs are maintained in the rdkcentral/firebolt-manage-sdk.git GitHub repository.

You can see this API in the account.json OpenRPC JSON-Schema document.

Table of Contents

Usage

To use the Account module, you can import it into your project from the Firebolt SDK:

import { Account } from '@firebolt-js/manage-sdk'

Methods

listen

Listen for events from this module.

To listen to a specific event pass the event name as the first parameter:

Account.listen(event: string, (data: any) => void): Promise<bigint>

Parameters:

Param Type Required Summary
event string Yes The event to listen for, see Events.
callback function Yes A function that will be invoked when the event occurs.

Promise resolution:

Type Description
bigint Listener ID to clear the callback method and stop receiving the event, e.g. Account.clear(id)

Callback parameters:

Param Type Required Summary
data any Yes The event data, which depends on which event is firing, see Events.

To listen to all events from this module pass only a callback, without specifying an event name:

Account.listen((event: string, data: any) => void): Promise<bigint>

Parameters:

Param Type Required Summary
callback function Yes A function that will be invoked when the event occurs. The event data depends on which event is firing, see Events.

Callback parameters:

Param Type Required Summary
event string Yes The event that has occured listen for, see Events.
data any Yes The event data, which depends on which event is firing, see Events.

Promise resolution:

Type Description
bigint Listener ID to clear the callback method and stop receiving the event, e.g. Account.clear(id)

See Listening for events for more information and examples.

once

Listen for only one occurance of an event from this module. The callback will be cleared after one event.

To listen to a specific event pass the event name as the first parameter:

Account.once(event: string, (data: any) => void): Promise<bigint>

Parameters:

Param Type Required Summary
event string Yes The event to listen for, see Events.
callback function Yes A function that will be invoked when the event occurs.

Promise resolution:

Type Description
bigint Listener ID to clear the callback method and stop receiving the event, e.g. Account.clear(id)

Callback parameters:

Param Type Required Summary
data any Yes The event data, which depends on which event is firing, see Events.

To listen to all events from this module pass only a callback, without specifying an event name:

Account.once((event: string, data: any) => void): Promise<bigint>

Parameters:

Param Type Required Summary
callback function Yes A function that will be invoked when the event occurs. The event data depends on which event is firing, see Events.

Callback parameters:

Param Type Required Summary
event string Yes The event that has occured listen for, see Events.
data any Yes The event data, which depends on which event is firing, see Events.

Promise resolution:

Type Description
bigint Listener ID to clear the callback method and stop receiving the event, e.g. Account.clear(id)

See Listening for events for more information and examples.

provide

Register to provide a capability from this module.

See Provider Interfaces, for more info.

function provide(provider: object | class): Promise<void>

Parameters:

Param Type Required Summary
provider `object class` true

Promise resolution:

void

session

Used by a distributor to push Session token to firebolt.

function session(token?: string, expiresIn?: bigint): Promise<void>

Parameters:

Param Type Required Summary
token string false
expiresIn bigint false
minumum: 1

Promise resolution:

void

Examples

Default Example

JavaScript:

import { Account } from '@firebolt-js/manage-sdk'

Account.session("RmlyZWJvbHQgTWFuYWdlIFNESyBSb2NrcyEhIQ==", 84000)
    .then(result => {
        console.log(result)
    })

Value of result:

null
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "account.session",
  "params": {
    "token": "RmlyZWJvbHQgTWFuYWdlIFNESyBSb2NrcyEhIQ==",
    "expiresIn": 84000
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

Additional methods

The following methods are documented as part of a related set of method APIs.

For more information, follow the links under the "Documentation" column.

JavaScript RPC Parameters Documentation
NA sessionFocus ()
NA sessionResponse (response: ProviderResponse) SessionProvider

Events

Additional events

The following events are documented as part of a related set of method APIs.

For more information, follow the links under the "Documentation" column.

JavaScript RPC Payload Documentation
NA onRequestSession object

Provider Interfaces

Providers are interfaces that your app can implement in order to provide certain capabilties back to the platform.

To register a provider, use the provide() method.

Every provider interface method has the following signature:

(parameters: object | void, session: ProviderSession) => {}

ProviderSession has the following interface:

interface ProviderSession {
    correlationId(): string        // Returns the correlation id of the current provider session
}


interface FocusableProviderSession extends ProviderSession {
    focus(): Promise<void>         // Requests that the provider app be moved into focus to prevent a user experience
}

SessionProvider

The provider interface for the xrn:firebolt:capability:account:session capability.

interface SessionProvider {
	session(parameters?: void, session?: FocusableProviderSession): Promise<object>
}

Usage:

Account.provide('xrn:firebolt:capability:account:session', provider: SessionProvider | object)

session

Registers as a provider for when device needs a session

function session(parameters?: void, session?: FocusableProviderSession): Promise<object>

Provider methods always have two arguments:

Param Type Required Summary
parameters void false
session FocusableProviderSession false

Promise resolution:

Field Type Description
token string Encoded token provided by the Distributor for Device Authentication.
expiresIn bigint Number of secs before the token expires

Examples

Register your app to provide the xrn:firebolt:capability:account:session capability.

import { Account } from '@firebolt-js/manage-sdk'

class MySessionProvider {

    async session(parameters, session) {
        return await Promise.resolve({
            "token": "RmlyZWJvbHQgTWFuYWdlIFNESyBSb2NrcyEhIQ==",
            "expiresIn": 84000
        })
    }

}

Account.provide('xrn:firebolt:capability:account:session', new MySessionProvider())
**JSON-RPC**

Register to recieve each provider API

Request:

{
    "id": 1,
    "method": "onRequestSession",
    "params": {
        "listen": true
    }
}

Response:

{
    "id": 1,
    "result": {
        "listening": true,
        "event": "Account.onRequestSession"
    }            
 
}

Asynchronous event to initiate session()

Event Response:

{
    "id": 1,
    "result": {
        "correlationId": "abc",
        "parameters": null
    }
}

App initiated response to event

Request:

{
    "id": 2,
    "method": "sessionResponse",
    "params": {
        "response": {
            "correlationId": "abc",
            "result": {
                "token": "RmlyZWJvbHQgTWFuYWdlIFNESyBSb2NrcyEhIQ==",
                "expiresIn": 84000
            }
        }
    }
}

Response:

{
    "id": 2,
    "result": true
}

Schemas

Token

Encoded token provided by the Distributor for Device Authentication.

type Token = string

Expiry

Number of secs before the token expires

type Expiry = bigint

Session

Session Token from the distributor.

type Session = {
  token?: string      // Encoded token provided by the Distributor for Device Authentication.
  expiresIn?: bigint  // Number of secs before the token expires
}
Clone this wiki locally