@pbvision/partner-sdk 0.1.17 → 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)
@@ -316,12 +317,15 @@ person recording can't change either. Ask for 4K with `resolution: '4k'` or
 60 FPS with `fps: 60`; with `mayChangeResolution: true` or `mayChangeFPS: true`
 the person recording may choose lower settings. Phones step down to what they
 support, and recorders don't need a PB Vision subscription. 4K requires your
-partner account to have 4K enabled.
+partner account to have 4K enabled, since PB Vision doesn't analyze video above
+1080p without it. `getMyPartnerAccountInfo()` says whether yours does, and
+without it `makeRecordingLink()` refuses `resolution: '4k'`.
 
 ```javascript
+const { is4K } = await pbv.getMyPartnerAccountInfo();
 const { url } = await pbv.makeRecordingLink({
   fid,
-  resolution: '4k',          // '1080p' (default) or '4k'
+  resolution: is4K ? '4k' : '1080p', // '1080p' (default) or '4k'
   fps: 60,                   // 30 (default) or 60
   mayChangeResolution: true, // default false
   mayChangeFPS: false        // default false
@@ -339,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.17",
+  "version": "0.1.19",
   "license": "MIT",
   "type": "module",
   "engines": {

package/src/index.js

@@ -68,6 +68,26 @@ export class PBVision {
     this.isDev = config === ENVIRONMENTS.test
   }
 
+  /**
+   * @typedef {Object} PartnerAccountInfo
+   * @property {boolean} is4K whether your partner account may upload video
+   *   above 1080p. Without 4K, PB Vision does not analyze such a video.
+   */
+
+  /**
+   * Tells you what your partner account may do, e.g. whether to offer 4K.
+   *
+   * @returns {PartnerAccountInfo}
+   */
+  async getMyPartnerAccountInfo () {
+    const resp = await this.__callAPI('about', {})
+    const { is4K } = JSON.parse(resp)
+    if (is4K) {
+      this.__is4K = true
+    }
+    return { is4K }
+  }
+
   /**
    * Tells PB Vision to make an HTTP POST request your URL after each of your
    * videos is done processing.
@@ -274,9 +294,10 @@ export class PBVision {
    * By default the app records at 1080p and 30 FPS, and the person recording
    * can't change either. A phone that can't record what the link asks for
    * steps down to the best quality it supports. The link's settings apply
-   * regardless of the recorder's own PB Vision subscription, but 4K requires
-   * your partner account to have 4K enabled; otherwise PB Vision rejects the
-   * upload.
+   * regardless of the recorder's own PB Vision subscription. 4K requires your
+   * partner account to have 4K enabled (see getMyPartnerAccountInfo()), so
+   * without it this refuses a 4K link rather than make a video PB Vision
+   * won't analyze.
    *
    * Each link is for one recording: only the first upload to its video
    * counts, so make a new link for each game. If several people may ask for
@@ -293,8 +314,9 @@ export class PBVision {
    * @param {RecordingLinkOptions} [options]
    * @returns {RecordingLink}
    * @throws {Error} if gameStartEpoch is given, a camera setting is invalid,
-   *   or PB Vision doesn't make the video (e.g. because the account paying for
-   *   it can't pay for it)
+   *   4K is asked for and your partner account doesn't have 4K, or PB Vision
+   *   doesn't make the video (e.g. because the account paying for it can't
+   *   pay for it)
    */
   async makeRecordingLink ({
     resolution = '1080p', fps = 30, mayChangeResolution = false, mayChangeFPS = false,
@@ -308,6 +330,13 @@ export class PBVision {
     assert(typeof mayChangeResolution === 'boolean', 'mayChangeResolution must be a boolean')
     assert(typeof mayChangeFPS === 'boolean', 'mayChangeFPS must be a boolean')
 
+    // checked before making the video, so a 4K link that PB Vision wouldn't
+    // analyze never gets one; only a yes is remembered, so an account that
+    // gets 4K later can ask for it without a new PBVision
+    if (resolution === '4k' && !this.__is4K && !(await this.getMyPartnerAccountInfo()).is4K) {
+      throw new Error('your partner account does not have 4K enabled, so PB Vision would not analyze a 4K recording; ask for 1080p, or ask PB Vision to enable 4K')
+    }
+
     const { vid, uid, hasCredits } = await this.makeVideoId({
       fileExt: 'mp4', userEmails, name, desc, facility, court, fid, playersForTagging, nonce })
     if (hasCredits === false) {
@@ -330,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.
    *