chore: Publish pr-feature-user-interest

rdkcentral · May 28, 2024 · 90e5481 · 90e5481
1 parent ef92a50
commit 90e5481
Show file tree

Hide file tree

Showing 6 changed files with 106 additions and 60 deletions.
diff --git 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
@@ -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
@@ -212,6 +212,19 @@ The schemas are used to generate SDK and Documentation artifacts.
 | [Discovery.entityInfo](./core/Discovery/#entityinfo)<br/>[Discovery.onPullEntityInfo](./core/Discovery/#pullentityinfo) |
 
 
+### `xrn:firebolt:capability:discovery:interest`
+
+| Uses |
+| ---- |
+| [Content.requestUserInterest](./manage/Content/#requestuserinterest)<br/>[Content.onUserInterest](./manage/Content/#userinterest) |
+
+
+
+| Provides |
+| -------- |
+| [Discovery.userInterest](./core/Discovery/#userinterest)<br/>[Discovery.onRequestUserInterest](./core/Discovery/#requestuserinterest)<br/>[Discovery.userInterestResponse](./core/Discovery/#userinterestresponse)<br/>[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)<br/>[Discovery.onSignOut](./manage/Discovery/#signout) |
 
 
-### `xrn:firebolt:capability:discovery:user-interest`
-
-| Uses |
-| ---- |
-| [Content.requestUserInterest](./manage/Content/#requestuserinterest)<br/>[Content.onUserInterest](./manage/Content/#userinterest) |
-
-
-
-| Provides |
-| -------- |
-| [Discovery.userInterest](./core/Discovery/#userinterest)<br/>[Discovery.onRequestUserInterest](./core/Discovery/#requestuserinterest)<br/>[Discovery.userInterestResponse](./core/Discovery/#userinterestresponse)<br/>[Discovery.userInterestError](./core/Discovery/#userinteresterror) |
-
-
 ### `xrn:firebolt:capability:discovery:watch-next`
 
 | Uses |

diff --git a/...ements/pr-feature-user-interest/specifications/discovery/user-interest/index.md b/...ements/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
@@ -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
@@ -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"
 						}
 					],