From 90e5481f3d2f99a2e1d7f4b7f6dcbcd73458123f Mon Sep 17 00:00:00 2001 From: Your Name Date: Tue, 28 May 2024 20:27:55 +0000 Subject: [PATCH] chore: Publish pr-feature-user-interest --- .../core/Discovery/index.md | 32 ++++++------- .../discovery/Content/index.md | 12 ++--- apis/pr-feature-user-interest/index.md | 26 +++++----- .../discovery/user-interest/index.md | 48 ++++++++++++++++++- .../specifications/firebolt-open-rpc.json | 12 ++--- .../firebolt-specification.json | 36 +++++++------- 6 files changed, 106 insertions(+), 60 deletions(-) diff --git a/apis/pr-feature-user-interest/core/Discovery/index.md b/apis/pr-feature-user-interest/core/Discovery/index.md index a1b8c8716..e4e0b8f5a 100644 --- a/apis/pr-feature-user-interest/core/Discovery/index.md +++ b/apis/pr-feature-user-interest/core/Discovery/index.md @@ -3359,9 +3359,9 @@ Promise resolution: Capabilities: -| Role | Capability | -| -------- | ----------------------------------------------- | -| provides | xrn:firebolt:capability:discovery:user-interest | +| Role | Capability | +| -------- | ------------------------------------------ | +| provides | xrn:firebolt:capability:discovery:interest | #### Examples @@ -3444,9 +3444,9 @@ Result: Capabilities: -| Role | Capability | -| -------- | ----------------------------------------------- | -| provides | xrn:firebolt:capability:discovery:user-interest | +| Role | Capability | +| -------- | ------------------------------------------ | +| provides | xrn:firebolt:capability:discovery:interest | #### Examples @@ -3500,9 +3500,9 @@ Result: Capabilities: -| Role | Capability | -| -------- | ----------------------------------------------- | -| provides | xrn:firebolt:capability:discovery:user-interest | +| Role | Capability | +| -------- | ------------------------------------------ | +| provides | xrn:firebolt:capability:discovery:interest | #### Examples @@ -3908,9 +3908,9 @@ Result: Capabilities: -| Role | Capability | -| -------- | ----------------------------------------------- | -| provides | xrn:firebolt:capability:discovery:user-interest | +| Role | Capability | +| -------- | ------------------------------------------ | +| provides | xrn:firebolt:capability:discovery:interest | #### Examples @@ -3953,7 +3953,7 @@ Response: ### UserInterestProvider -The provider interface for the `xrn:firebolt:capability:discovery:user-interest` capability. +The provider interface for the `xrn:firebolt:capability:discovery:interest` capability. ```typescript interface UserInterestProvider { @@ -3967,12 +3967,12 @@ interface UserInterestProvider { Usage: ```typescript -Discovery.provide('xrn:firebolt:capability:discovery:user-interest', provider: UserInterestProvider | object) +Discovery.provide('xrn:firebolt:capability:discovery:interest', provider: UserInterestProvider | object) ``` #### Examples -**Register your app to provide the `xrn:firebolt:capability:discovery:user-interest` capability.** +**Register your app to provide the `xrn:firebolt:capability:discovery:interest` capability.** ```javascript import { Discovery } from '@firebolt-js/sdk' @@ -4006,7 +4006,7 @@ class MyUserInterestProvider { } Discovery.provide( - 'xrn:firebolt:capability:discovery:user-interest', + 'xrn:firebolt:capability:discovery:interest', new MyUserInterestProvider(), ) ``` diff --git a/apis/pr-feature-user-interest/discovery/Content/index.md b/apis/pr-feature-user-interest/discovery/Content/index.md index b62f0e009..dfac41884 100644 --- a/apis/pr-feature-user-interest/discovery/Content/index.md +++ b/apis/pr-feature-user-interest/discovery/Content/index.md @@ -175,9 +175,9 @@ Promise resolution: Capabilities: -| Role | Capability | -| ---- | ----------------------------------------------- | -| uses | xrn:firebolt:capability:discovery:user-interest | +| Role | Capability | +| ---- | ------------------------------------------ | +| uses | xrn:firebolt:capability:discovery:interest | #### Examples @@ -292,9 +292,9 @@ Event value: Capabilities: -| Role | Capability | -| ---- | ----------------------------------------------- | -| uses | xrn:firebolt:capability:discovery:user-interest | +| Role | Capability | +| ---- | ------------------------------------------ | +| uses | xrn:firebolt:capability:discovery:interest | #### Examples diff --git a/apis/pr-feature-user-interest/index.md b/apis/pr-feature-user-interest/index.md index b4dab3f71..a2b60771c 100644 --- a/apis/pr-feature-user-interest/index.md +++ b/apis/pr-feature-user-interest/index.md @@ -212,6 +212,19 @@ The schemas are used to generate SDK and Documentation artifacts. | [Discovery.entityInfo](./core/Discovery/#entityinfo)
[Discovery.onPullEntityInfo](./core/Discovery/#pullentityinfo) | +### `xrn:firebolt:capability:discovery:interest` + +| Uses | +| ---- | +| [Content.requestUserInterest](./manage/Content/#requestuserinterest)
[Content.onUserInterest](./manage/Content/#userinterest) | + + + +| Provides | +| -------- | +| [Discovery.userInterest](./core/Discovery/#userinterest)
[Discovery.onRequestUserInterest](./core/Discovery/#requestuserinterest)
[Discovery.userInterestResponse](./core/Discovery/#userinterestresponse)
[Discovery.userInterestError](./core/Discovery/#userinteresterror) | + + ### `xrn:firebolt:capability:discovery:navigate-to` | Uses | @@ -246,19 +259,6 @@ The schemas are used to generate SDK and Documentation artifacts. | [Discovery.onSignIn](./manage/Discovery/#signin)
[Discovery.onSignOut](./manage/Discovery/#signout) | -### `xrn:firebolt:capability:discovery:user-interest` - -| Uses | -| ---- | -| [Content.requestUserInterest](./manage/Content/#requestuserinterest)
[Content.onUserInterest](./manage/Content/#userinterest) | - - - -| Provides | -| -------- | -| [Discovery.userInterest](./core/Discovery/#userinterest)
[Discovery.onRequestUserInterest](./core/Discovery/#requestuserinterest)
[Discovery.userInterestResponse](./core/Discovery/#userinterestresponse)
[Discovery.userInterestError](./core/Discovery/#userinteresterror) | - - ### `xrn:firebolt:capability:discovery:watch-next` | Uses | diff --git a/requirements/pr-feature-user-interest/specifications/discovery/user-interest/index.md b/requirements/pr-feature-user-interest/specifications/discovery/user-interest/index.md index ec9d14343..bcab837eb 100644 --- a/requirements/pr-feature-user-interest/specifications/discovery/user-interest/index.md +++ b/requirements/pr-feature-user-interest/specifications/discovery/user-interest/index.md @@ -62,6 +62,7 @@ track of which apps are using them separately. - [3. User Interest Flows](#3-user-interest-flows) - [3.1. User Interest from an in-app UX](#31-user-interest-from-an-in-app-ux) - [3.2. User Interest from a platform UX](#32-user-interest-from-a-platform-ux) + - [User Interest Errors](#user-interest-errors) - [3.3. Upstream User Interest Intent](#33-upstream-user-interest-intent) - [3.4. User Interest Bulk Updates](#34-user-interest-bulk-updates) - [4. Core SDK APIs](#4-core-sdk-apis) @@ -138,7 +139,7 @@ An app **MUST** have permissions to `use` the `xrn:firebolt:capability:discovery:interest` capability in order to listen to the `Content.onUserInterest` notification. -If the result is `null` or is not a valid entity, i.e. does not match +If the result is not a valid entity, i.e. does not match the [EntityDetails](../../entities/) schema, then no `Content.onUserInterestedIn` notification will be dispatched. @@ -196,6 +197,51 @@ then, the returned value **MUST** be used. If there is no app registered the an error **MUST** be returned. +#### User Interest Errors +An app is expected return either a valid result or an appriate error. + +If neither happens before `interestTimeout` expires then the platform **MUST** return a Provider timed-out error: + +```json +{ + "id": 1, + "error": { + "code": -50400, + "message": "Provider timed-out", + "data": { + "capability": "xrn:firebolt:capability:discovery:interest", + } + } +} +``` + +If an app recieves a request for user interest when there is nothing appropriate to return, e.g. nothing selected or presented that maps to an Entity, then the app **SHOULD** return an error with a valid JSON-RPC error response, e.g.: + +```json +{ + "id": 1, + "error": { + "code": -40400, + "message": "No entities currently presented." + } +} +``` + +The platform API Gateway **MUST** append, or overwrite, the `data.capability` value to any errors returned by the app, e.g.: + +```json +{ + "id": 1, + "error": { + "code": -40400, + "message": "No entities currently presented.", + "data": { + "capability": "xrn:firebolt:capability:discovery:interest", + } + } +} +``` + ### 3.3. Upstream User Interest Intent In some cases, e.g. a voice assistant, some upstream component will inform the platform that the user is interested in whatever is currently being presented. diff --git a/requirements/pr-feature-user-interest/specifications/firebolt-open-rpc.json b/requirements/pr-feature-user-interest/specifications/firebolt-open-rpc.json index 707be6cc3..822077aba 100644 --- a/requirements/pr-feature-user-interest/specifications/firebolt-open-rpc.json +++ b/requirements/pr-feature-user-interest/specifications/firebolt-open-rpc.json @@ -5634,7 +5634,7 @@ "name": "capabilities", "x-provided-by": "Discovery.onRequestUserInterest", "x-uses": [ - "xrn:firebolt:capability:discovery:user-interest" + "xrn:firebolt:capability:discovery:interest" ] } ], @@ -5717,7 +5717,7 @@ "name": "capabilities", "x-provided-by": "Discovery.userInterest", "x-uses": [ - "xrn:firebolt:capability:discovery:user-interest" + "xrn:firebolt:capability:discovery:interest" ] } ], @@ -8606,7 +8606,7 @@ "tags": [ { "name": "capabilities", - "x-provides": "xrn:firebolt:capability:discovery:user-interest" + "x-provides": "xrn:firebolt:capability:discovery:interest" } ], "params": [ @@ -8732,7 +8732,7 @@ }, { "name": "capabilities", - "x-provides": "xrn:firebolt:capability:discovery:user-interest" + "x-provides": "xrn:firebolt:capability:discovery:interest" } ], "summary": "Provide information about the entity currently displayed or selected on the screen.", @@ -9030,7 +9030,7 @@ }, { "name": "capabilities", - "x-provides": "xrn:firebolt:capability:discovery:user-interest", + "x-provides": "xrn:firebolt:capability:discovery:interest", "x-response-for": "Discovery.onRequestUserInterest" } ], @@ -9131,7 +9131,7 @@ }, { "name": "capabilities", - "x-provides": "xrn:firebolt:capability:discovery:user-interest", + "x-provides": "xrn:firebolt:capability:discovery:interest", "x-error-for": "Discovery.onRequestUserInterest" } ], diff --git a/requirements/pr-feature-user-interest/specifications/firebolt-specification.json b/requirements/pr-feature-user-interest/specifications/firebolt-specification.json index 59c878de5..a7c8af0e5 100644 --- a/requirements/pr-feature-user-interest/specifications/firebolt-specification.json +++ b/requirements/pr-feature-user-interest/specifications/firebolt-specification.json @@ -696,7 +696,7 @@ "negotiable": true } }, - "xrn:firebolt:capability:discovery:navigate-to": { + "xrn:firebolt:capability:discovery:interest": { "level": "must", "use": { "public": true, @@ -707,11 +707,11 @@ "negotiable": false }, "provide": { - "public": false, - "negotiable": false + "public": true, + "negotiable": true } }, - "xrn:firebolt:capability:discovery:policy": { + "xrn:firebolt:capability:discovery:navigate-to": { "level": "must", "use": { "public": true, @@ -726,26 +726,26 @@ "negotiable": false } }, - "xrn:firebolt:capability:discovery:purchased-content": { + "xrn:firebolt:capability:discovery:policy": { "level": "must", "use": { - "public": false, - "negotiable": false + "public": true, + "negotiable": true }, "manage": { "public": false, "negotiable": false }, "provide": { - "public": true, - "negotiable": true + "public": false, + "negotiable": false } }, - "xrn:firebolt:capability:discovery:user-interest": { + "xrn:firebolt:capability:discovery:purchased-content": { "level": "must", "use": { - "public": true, - "negotiable": true + "public": false, + "negotiable": false }, "manage": { "public": false, @@ -6559,7 +6559,7 @@ "name": "capabilities", "x-provided-by": "Discovery.onRequestUserInterest", "x-uses": [ - "xrn:firebolt:capability:discovery:user-interest" + "xrn:firebolt:capability:discovery:interest" ] } ], @@ -6642,7 +6642,7 @@ "name": "capabilities", "x-provided-by": "Discovery.userInterest", "x-uses": [ - "xrn:firebolt:capability:discovery:user-interest" + "xrn:firebolt:capability:discovery:interest" ] } ], @@ -9531,7 +9531,7 @@ "tags": [ { "name": "capabilities", - "x-provides": "xrn:firebolt:capability:discovery:user-interest" + "x-provides": "xrn:firebolt:capability:discovery:interest" } ], "params": [ @@ -9657,7 +9657,7 @@ }, { "name": "capabilities", - "x-provides": "xrn:firebolt:capability:discovery:user-interest" + "x-provides": "xrn:firebolt:capability:discovery:interest" } ], "summary": "Provide information about the entity currently displayed or selected on the screen.", @@ -9955,7 +9955,7 @@ }, { "name": "capabilities", - "x-provides": "xrn:firebolt:capability:discovery:user-interest", + "x-provides": "xrn:firebolt:capability:discovery:interest", "x-response-for": "Discovery.onRequestUserInterest" } ], @@ -10056,7 +10056,7 @@ }, { "name": "capabilities", - "x-provides": "xrn:firebolt:capability:discovery:user-interest", + "x-provides": "xrn:firebolt:capability:discovery:interest", "x-error-for": "Discovery.onRequestUserInterest" } ],