AcknowledgeChallenge Module

Version 0.1.0-alpha.4

A module for registering as a provider for a user grant in which the user confirms access to a capability

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

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

• Overview

• OpenRPC

• Usage

• Methods

  • listen
  • once
  • provide
  • Additional Methods

• Events

  • Additional Events

• Provider Interfaces

  • ChallengeProvider

• Schemas

  • ChallengeRequestor
  • Challenge
  • ChallengeProviderRequest
  • GrantResult

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

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

Listen for events from this module.

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

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

Parameters:

Promise resolution:

Callback parameters:

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

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

Parameters:

Callback parameters:

Promise resolution:

See Listening for events for more information and examples.

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:

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

Parameters:

Promise resolution:

Callback parameters:

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

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

Parameters:

Callback parameters:

Promise resolution:

See Listening for events for more information and examples.

Register to provide a capability from this module.

See Provider Interfaces, for more info.

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

Parameters:

Promise resolution:

void

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

For more information, follow the links under the “Documentation” column.

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

For more information, follow the links under the “Documentation” column.

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
}

The provider interface for the xrn:firebolt:capability:usergrant:acknowledgechallenge capability.

interface ChallengeProvider {
	challenge(parameters?: Challenge, session?: FocusableProviderSession): Promise<GrantResult>
}

Usage:

AcknowledgeChallenge.provide('xrn:firebolt:capability:usergrant:acknowledgechallenge', provider: ChallengeProvider | object)

Registers as a provider for when the user should be challenged in order to confirm access to a capability

function challenge(parameters?: Challenge, session?: FocusableProviderSession): Promise<GrantResult>

Provider methods always have two arguments:

type Challenge = object

Promise resolution:

Register your app to provide the xrn:firebolt:capability:usergrant:acknowledgechallenge capability.

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

class MyChallengeProvider {

    async challenge(parameters, session) {
        return await Promise.resolve({
            "granted": true
        })
    }

}

AcknowledgeChallenge.provide('xrn:firebolt:capability:usergrant:acknowledgechallenge', new MyChallengeProvider())

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

{
    "id": 1,
    "result": {
        "listening": true,
        "event": "AcknowledgeChallenge.onRequestChallenge"
    }            
 
}

{
    "id": 1,
    "result": {
        "correlationId": "abc",
        "parameters": {
            "capability": "xrn:firebolt:capability:localization::postalcode",
            "requestor": {
                "id": "ReferenceApp",
                "name": "Firebolt Reference App"
            }
        }
    }
}

{
    "id": 2,
    "method": "challengeResponse",
    "params": {
        "response": {
            "correlationId": "abc",
            "result": {
                "granted": true
            }
        }
    }
}

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

type ChallengeRequestor = {
  id: string                 // The id of the app that requested the challenge
  name: string               // The name of the app that requested the challenge
}

type Challenge = {
  capability: string             // The capability that is being requested by the user to approve
  requestor: ChallengeRequestor
}

type ChallengeProviderRequest = {
  correlationId: string            // The id that was passed in to the event that triggered a provider method to be called
  parameters: Challenge
}

See also:

• ProviderRequest

type GrantResult = {
  granted: boolean    // Whether the user approved or denied the challenge
}