@pbvision/partner-sdk 0.1.18 → 0.1.20

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)
@@ -168,6 +169,7 @@ entirely, or provide some or all of these fields:
 | `facility` | `string` | Name of the facility where the game was recorded, e.g. `"Cool Club #3 - Barcelona"`. Useful for facility and Court Insight integrations. |
 | `court` | `string` | Court identifier where the game was recorded, e.g. `"11A"`. Useful for facility and Court Insight integrations. |
 | `fid` | `integer` | Folder ID, e.g. from `getOrCreateFolder()` (see [Folders](#folders)). Puts the video in that folder in your partner account's library. A `fid` that isn't one of your folders is refused with a 400 error (`unknown folder`). |
+| `playersFolderPath` | `string[]` | Where the video goes in the PB Vision library of everyone it's shared with: the folder names from the top of their library down, e.g. `['Mon Oct 19 open play']`. 1 to 5 names, each 1 to 200 characters with no leading or trailing whitespace. Folders they don't have are made for them. |
 | `playersForTagging` | `object` | The players to **auto-tag** once processing completes, each by a name, an email, or both (see [Auto-tagging players](#auto-tagging-players)). Honored by all of `uploadVideo()`, `sendVideoUrlToDownload()`, `makeVideoId()`, and `makeRecordingLink()`. |
 
 The `facility` and `court` fields are primarily used by facility partners
@@ -218,7 +220,8 @@ games automatically.
 
 Folders organize the videos in your partner account's library. To put a new
 video in a folder, pass the folder's ID as the `fid` [metadata](#video-metadata)
-field.
+field. To file it in the libraries of the people it's shared with, pass
+`playersFolderPath`.
 
 `getOrCreateFolder()` returns the folder with the name you give (inside
 `parent`, if you pass one), creating it if needed, so it's safe to retry. Use a
@@ -342,6 +345,26 @@ 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. A
+score someone enters in PB Vision itself stands, though: a report never
+replaces it, and `applied` is false. 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.20",
   "license": "MIT",
   "type": "module",
   "engines": {

package/src/index.js

@@ -139,13 +139,14 @@ export class PBVision {
    * @param {VideoMetadata} [metadata]
    * @returns {VideoUrlToDownloadResponse}
    */
-  async sendVideoUrlToDownload (videoUrl, { userEmails = [], name, desc, gameStartEpoch, facility, court, fid, playersForTagging } = {}) {
+  async sendVideoUrlToDownload (videoUrl, { userEmails = [], name, desc, gameStartEpoch, facility, court, fid, playersFolderPath, playersForTagging } = {}) {
     assert(typeof videoUrl === 'string' && videoUrl.startsWith('http'),
       'URL must be a string beginning with http')
     assert(videoUrl.split('?')[0].endsWith('.mp4'), 'video URL must have the .mp4 extension')
+    assertFolderPath(playersFolderPath)
     const resp = await this.__callAPI(
       'add_video_by_url',
-      { url: videoUrl, userEmails, name, desc, gameStartEpoch, facility, court, fid, playersForTagging })
+      { url: videoUrl, userEmails, name, desc, gameStartEpoch, facility, court, fid, playersFolderPath, playersForTagging })
     return JSON.parse(resp)
   }
 
@@ -182,6 +183,12 @@ export class PBVision {
    * @property {integer} [fid] the ID of the folder in your partner account's
    *   library to add this video to (see getOrCreateFolder()). A fid that is
    *   not one of your folders is refused.
+   * @property {Array<string>} [playersFolderPath] where this video goes in
+   *   the PB Vision library of everyone it's shared with: the folder names
+   *   from the top of their library down, e.g. ['Mon Oct 19 open play'] or
+   *   ['Open play', 'Oct 19']. Folders they don't have are made for them.
+   *   1 to 5 names, each 1 to 200 characters with no leading or trailing
+   *   whitespace.
    * @property {PlayersForTagging} [playersForTagging] the players to tag
    *   automatically once processing completes, each by a name, an email, or
    *   both. Identify players by their role at the start of the first game.
@@ -238,9 +245,10 @@ export class PBVision {
    *   no `vid`, when the account paying for the video can't pay for it; for
    *   passthrough partners it is always present.
    */
-  async makeVideoId ({ fileExt = 'mp4', userEmails = [], name, desc, gameStartEpoch, facility, court, fid, playersForTagging, nonce } = {}) {
+  async makeVideoId ({ fileExt = 'mp4', userEmails = [], name, desc, gameStartEpoch, facility, court, fid, playersFolderPath, playersForTagging, nonce } = {}) {
+    assertFolderPath(playersFolderPath)
     const resp = await this.__callAPI('make_video_id',
-      { platform: getPlatform(), fileExt, userEmails, name, desc, gameStartEpoch, facility, court, fid, playersForTagging, nonce })
+      { platform: getPlatform(), fileExt, userEmails, name, desc, gameStartEpoch, facility, court, fid, playersFolderPath, playersForTagging, nonce })
     const { hasCredits, vid } = JSON.parse(resp)
     const ret = { vid, uid: this.uid }
     if (hasCredits !== undefined) {
@@ -262,6 +270,8 @@ export class PBVision {
    * @property {string} [court] the court where the game is played
    * @property {integer} [fid] the ID of the folder in your partner account's
    *   library to add the video to (see getOrCreateFolder())
+   * @property {Array<string>} [playersFolderPath] where the video goes in
+   *   the library of everyone it's shared with (see VideoMetadata)
    * @property {PlayersForTagging} [playersForTagging] the players to tag
    *   automatically once processing completes
    * @property {string} [nonce] identifies the game, e.g. your own ID for it:
@@ -320,7 +330,7 @@ export class PBVision {
    */
   async makeRecordingLink ({
     resolution = '1080p', fps = 30, mayChangeResolution = false, mayChangeFPS = false,
-    gameStartEpoch, userEmails, name, desc, facility, court, fid, playersForTagging, nonce
+    gameStartEpoch, userEmails, name, desc, facility, court, fid, playersFolderPath, playersForTagging, nonce
   } = {}) {
     assert(gameStartEpoch === undefined,
       'makeRecordingLink() does not take gameStartEpoch: the game\'s time comes from its recording, and a time set now would override it')
@@ -329,6 +339,7 @@ export class PBVision {
     assert(RECORDING_FPS.includes(fps), `fps must be 30 or 60, not ${JSON.stringify(fps)}`)
     assert(typeof mayChangeResolution === 'boolean', 'mayChangeResolution must be a boolean')
     assert(typeof mayChangeFPS === 'boolean', 'mayChangeFPS must be a boolean')
+    assertFolderPath(playersFolderPath)
 
     // 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
@@ -338,7 +349,7 @@ export class PBVision {
     }
 
     const { vid, uid, hasCredits } = await this.makeVideoId({
-      fileExt: 'mp4', userEmails, name, desc, facility, court, fid, playersForTagging, nonce })
+      fileExt: 'mp4', userEmails, name, desc, facility, court, fid, playersFolderPath, playersForTagging, nonce })
     if (hasCredits === false) {
       throw new Error('PB Vision did not make a video for this recording link: the account paying for it has no credits available (hasCredits is false)')
     }
@@ -359,6 +370,51 @@ 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 now. While
+   *   the video awaits processing, false, and processing gives the game the
+   *   score when it finishes. After, false means the game keeps the score it
+   *   has: someone entered it in PB Vision, or PB Vision couldn't tell which
+   *   team served first
+   */
+
+  /**
+   * 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, though never over a score someone entered in
+   * PB Vision itself.
+   *
+   * @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.
    *
@@ -604,6 +660,12 @@ async function startResumableUpload (bucket, objName, numBytesTotal) {
   }
 }
 
+// playersFolderPath is a list of folder names, not a single name
+function assertFolderPath (playersFolderPath) {
+  assert(playersFolderPath === undefined || Array.isArray(playersFolderPath),
+    'playersFolderPath must be an array of folder names, e.g. [\'Mon Oct 19 open play\']')
+}
+
 // GCS asks clients to retry these, with exponential backoff
 function isTemporaryStatus (status) {
   return status >= 500 || status === 408 || status === 429