@pbvision/partner-sdk 0.1.18 → 0.1.19

package/README.md

@@ -19,6 +19,7 @@ standard length game, so we'll notify your servers when the results are ready.
     - [Auto-tagging players](#auto-tagging-players)
   - [Folders](#folders)
   - [Recording with the PB Vision app](#recording-with-the-pb-vision-app)
+  - [Reporting a game's score](#reporting-a-games-score)
   - [Video Editors and Viewers](#video-editors-and-viewers)
 - [After Video Processing is Done](#after-video-processing-is-done)
   - [Callback Data](#callback-data)
@@ -342,6 +343,24 @@ shows a page for installing it.
 **Testing.** Links from the test server (`useProdServer: false`) start with
 `pbvision://record` and need a development build of the PB Vision app.
 
+### Reporting a game's score
+
+If you know a game's final score, report it with `setGameScore()` and PB
+Vision shows it with the game. Name each team by its role at the game's first
+serve, as in [`playersForTagging`](#auto-tagging-players): the team that served
+the first point, and the team that received it. Give the video by its `vid` or
+by the `nonce` you made it with.
+
+```javascript
+await pbv.setGameScore({ nonce: `${eventId}-${gameId}`, server: 11, receiver: 7 });
+```
+
+You can report before the video is processed, or even recorded: the game gets
+the score when processing finishes, and the response's `applied` says whether
+it has it yet. Report again to correct a score; the latest report wins. Each
+team's result is its points, or `'won'` or `'lost'` if that is all you know.
+The score is for a video of one game.
+
 ### Video Editors and Viewers
 
 Editors can tag themselves and friends in the video. Viewers have read-only

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pbvision/partner-sdk",
   "description": "SDK for interacting with the PB Vision pickleball AI engine.",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "license": "MIT",
   "type": "module",
   "engines": {

package/src/index.js

@@ -359,6 +359,48 @@ export class PBVision {
     return { vid, uid, url: `${this.recordUrl}?${query}` }
   }
 
+  /**
+   * One team's result in a game: the points it scored, `'won'` or `'lost'`
+   * when that is all you know, or `null` when you don't know it.
+   *
+   * @typedef {number|'won'|'lost'|null} TeamResult
+   */
+
+  /**
+   * @typedef {Object} SetGameScoreResponse
+   * @property {string} vid the video
+   * @property {boolean} applied whether the game has the score yet; false
+   *   while the video awaits processing, which gives the game the score when
+   *   it finishes
+   */
+
+  /**
+   * Reports the final score of a game you recorded, for a video of one game
+   * that your partner account owns. Name each team by its role at the game's
+   * first serve, as playersForTagging names the players: the team that
+   * served the first point, and the team that received it. You can report
+   * before the video is processed, or even recorded. Report again to correct
+   * it: the latest report wins.
+   *
+   * @param {Object} score
+   * @param {string} [score.vid] the video; give this or nonce
+   * @param {string} [score.nonce] the nonce you made the video with; give
+   *   this or vid
+   * @param {TeamResult} score.server the result of the team that served the
+   *   game's first point
+   * @param {TeamResult} score.receiver the result of the team that received
+   *   it
+   * @returns {SetGameScoreResponse}
+   */
+  async setGameScore ({ vid, nonce, server, receiver }) {
+    assert((vid === undefined) !== (nonce === undefined), 'give either vid or nonce')
+    const isResult = x => x === null || x === 'won' || x === 'lost' || (Number.isInteger(x) && x >= 0)
+    assert(isResult(server) && isResult(receiver),
+      'each team\'s result must be its points, \'won\', \'lost\' or null')
+    const resp = await this.__callAPI('video/score/set', { vid, nonce, server, receiver })
+    return JSON.parse(resp)
+  }
+
   /**
    * Upload a video for processing by the AI.
    *