@pbvision/partner-sdk 0.1.19 → 0.1.20

package/README.md

@@ -169,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
@@ -219,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
@@ -357,9 +359,11 @@ 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.
+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
 

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.19",
+  "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)')
     }
@@ -369,9 +380,11 @@ export class PBVision {
   /**
    * @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
+   * @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
    */
 
   /**
@@ -380,7 +393,8 @@ export class PBVision {
    * 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.
+   * 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
@@ -646,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