@pbvision/partner-sdk 0.1.13 → 0.1.15

package/README.md

@@ -1,5 +1,7 @@
 # PB Vision Partner Documentation <!-- omit in toc -->
 
+For policies, pricing, and partner responsibilities refer to our [API Partner Guide](https://help.pb.vision/en/help/articles/2793895-pb-vision-api-partner-guide).
+
 The easiest way to use the PB Vision AI Engine is to simply share a link to
 your video file. Our AI usually works on each video for about 30 minutes for a
 standard length game, so we'll notify your servers when the results are ready.
@@ -12,9 +14,16 @@ standard length game, so we'll notify your servers when the results are ready.
   - [Send Videos](#send-videos)
     - [Option 1: PBV downloads your video from a URL](#option-1-pbv-downloads-your-video-from-a-url)
     - [Option 2: Upload your video](#option-2-upload-your-video)
-  - [Video Editors](#video-editors)
+    - [Option 3: Pre-allocate a video ID (record/upload elsewhere)](#option-3-pre-allocate-a-video-id-recordupload-elsewhere)
+    - [Video Metadata](#video-metadata)
+    - [Auto-tagging players](#auto-tagging-players)
+  - [Folders](#folders)
+  - [Recording with the PB Vision app](#recording-with-the-pb-vision-app)
+  - [Video Editors and Viewers](#video-editors-and-viewers)
 - [After Video Processing is Done](#after-video-processing-is-done)
   - [Callback Data](#callback-data)
+  - [Fetching Insights by Video ID](#fetching-insights-by-video-id)
+  - [Player Identification](#player-identification)
 - [Video Guidelines](#video-guidelines)
 - [Reference Guide](#reference-guide)
 
@@ -80,13 +89,12 @@ Next, tell us to download and work on the video. You can do this using our SDK:
 import { PBVision } from '@pbvision/partner-sdk';
 
 const pbv = new PBVision(YOUR_API_KEY, { useProdServer: true });
-// you can omit this metadata, or provide some or all of this object—whatever you'd like!
-const optionalMetadata = {
-  userEmails: [], // these users will have the video in their PB Vision library
+const metadata = {
+  userEmails: ['player1@example.com', 'player2@example.com'],
   name: 'Dink Championship 2025',
-  gameStartEpoch: 1711393200, // when the game was played
+  gameStartEpoch: 1711393200,
 };
-await pbv.sendVideoUrlToDownload(YOUR_VIDEO_URL, optionalMetadata);
+const { vid } = await pbv.sendVideoUrlToDownload(YOUR_VIDEO_URL, metadata);
 ```
 
 Alternatively, you can just use `curl`:
@@ -107,24 +115,278 @@ You can directly upload your video from a file using the SDK too:
 import { PBVision } from '@pbvision/partner-sdk';
 
 const pbv = new PBVision(YOUR_API_KEY, { useProdServer: true });
-// you can omit this metadata, or provide some or all of this object—whatever you'd like!
-const optionalMetadata = {
-  userEmails: [], // these users will have the video in their PB Vision library
-  name: 'Dink Championship 2025',
-  gameStartEpoch: 1711393200, // when the game was played
+const metadata = {
+  userEmails: ['player1@example.com'],
+  name: 'My Game',
+  gameStartEpoch: 1711393200,
 };
-await pbv.uploadVideo(YOUR_VIDEO_FILENAME, optionalMetadata);
+const { vid } = await pbv.uploadVideo(YOUR_VIDEO_FILENAME, metadata);
+```
+
+`uploadVideo()` sends the file in chunks and resumes by itself after a dropped
+connection or a temporary error. If the upload still fails, the error it throws
+has the video's ID as its `vid` property. To retry without making a second
+video for the game, pass a `nonce` that identifies the game (see
+`makeVideoId()`): every call with the same nonce uploads to the same video.
+
+#### Option 3: Pre-allocate a video ID (record/upload elsewhere)
+
+Use `makeVideoId()` to reserve a video ID **without** uploading a file yourself.
+This is handy when the video will be recorded and uploaded by a different
+client. Hand the returned `vid` (and `uid`) to that client so it uploads to
+this video instead of allocating a new one.
+
+To have the game recorded with the PB Vision app, use `makeRecordingLink()`
+instead: it reserves the video ID for you and returns a link that opens the
+app's camera to record into it. See
+[Recording with the PB Vision app](#recording-with-the-pb-vision-app).
+
+```javascript
+const { vid, uid, hasCredits } = await pbv.makeVideoId({
+  // same metadata fields as the other upload methods (all optional)
+  name: 'My Game',
+  fileExt: 'mp4', // the extension it will be uploaded as (defaults to "mp4")
+  playersForTagging: { server: { name: 'Alice', email: 'alice@example.com' }, receiver: { name: 'Bob' } }
+});
+```
+
+If the account paying for the video can't pay for it, `hasCredits` is `false`
+and there is no `vid`. Passthrough partners always get `hasCredits`.
+
+#### Video Metadata
+
+`sendVideoUrlToDownload()`, `uploadVideo()`, `makeVideoId()`, and
+`makeRecordingLink()` accept an optional metadata object. You can omit it
+entirely, or provide some or all of these fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `userEmails` | `string[]` | Up to 4 email addresses of players in the game. These users will have the video added to their PB Vision library, become editors on the video, and be notified when processing is complete. |
+| `name` | `string` | Title of the game. Defaults to the game time, or the upload time if no game time is provided. |
+| `desc` | `string` | A longer description of the game. |
+| `gameStartEpoch` | `integer` | Unix timestamp (seconds) of when the game was played. Not taken by `makeRecordingLink()`, where the game's time comes from its recording. |
+| `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`). |
+| `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
+running [Court Insight](https://help.pb.vision/en/articles/9341690-court-insight-for-facilities-and-clubs)
+or similar venue-based integrations, where tracking which court a game came from
+is important. League and tournament partners may also find these useful for
+organizing videos by location.
+
+#### Auto-tagging players
+
+Provide `playersForTagging` to have PB Vision tag the players automatically
+once the video is processed. Identify each player by their **role at the start
+of the first game**, and give each one a `name`, an `email`, or both:
+
+```javascript
+const { vid } = await pbv.uploadVideo(YOUR_VIDEO_FILENAME, {
+  playersForTagging: {
+    server: { name: 'Alice', email: 'alice@example.com' },       // served the first point
+    serverPartner: { name: 'Carol' },                            // omit for singles
+    receiver: { email: 'bob@example.com' },                      // received the first point
+    receiverPartner: { name: 'Dave', email: 'dave@example.com' } // omit for singles
+  }
+});
+```
+
+To fill in the roles from a match:
+
+- The team that serves first supplies the `server` (its first server) and the
+  `serverPartner`.
+- The other team's first server is the `receiver`: they start on the right and
+  receive the first serve. Their partner is the `receiverPartner`.
+- For singles, omit `serverPartner` and `receiverPartner`.
+
+How each player is tagged depends on what you provide:
+
+- A player with an `email` is emailed that they were tagged. If the email
+  belongs to a PB Vision account, the game is added to that account's library
+  and the account's own name is shown. If not, the `name` you gave is shown,
+  and the game joins their library when they sign up with that email.
+- A player with only a `name` is labeled with that name.
+
+`server` and `receiver` are required when `playersForTagging` is present.
+Names are 1 to 64 characters (after trimming), and each email may be used for
+only one player. In multi-game videos the same players are matched across
+games automatically.
+
+### Folders
+
+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.
+
+`getOrCreateFolder()` returns the folder in your library with exactly the name
+you give (inside `parent`, if you pass one), creating it if there is none.
+Calling it again with the same name returns the same folder, as long as you
+haven't renamed or moved it since, so it is safe to retry. Use a unique name
+for each event, such as one that includes its date; otherwise two events with
+the same name would share one folder. Names are 1 to 200 characters, with no
+leading or trailing whitespace.
+
+```javascript
+// a folder at the top level of your library
+const { fid, created } = await pbv.getOrCreateFolder('Spring Open 2026-04-18');
+
+// a folder inside it
+const { fid: day1Fid } = await pbv.getOrCreateFolder('Day 1', { parent: fid });
+```
+
+`created` is `true` if the call made the folder, or `false` if it already
+existed.
+
+`updateFolder()` renames a folder, moves it, or makes it public. Fields you
+leave out stay as they are:
+
+```javascript
+await pbv.updateFolder(fid, { name: 'Spring Open 2026' }); // rename it
+await pbv.updateFolder(day1Fid, { parent: null });         // move it to the top level
+await pbv.updateFolder(fid, { public: true });             // let anyone with its link view it
+await pbv.updateFolder(day1Fid, { public: true });         // and include Day 1 when it's viewed
+```
+
+Anyone with a public folder's link can view its videos, signed in to PB Vision
+or not. A folder inside it is only included if it is public too, so make each
+folder you want shared public (the folders PB Vision makes to hold the games of
+a multi-game video follow their parent). `getPublicFolderUrl()` gives you the
+link:
+
+```javascript
+const folderUrl = pbv.getPublicFolderUrl(fid);
+// https://pb.vision/library/public/<uid>/<fid>
+```
+
+### Recording with the PB Vision app
+
+The PB Vision iOS and Android apps can record a game straight into your
+partner account. For each game, `makeRecordingLink()` makes a video with the
+[metadata](#video-metadata) you give it and returns a link. Opening the link on
+a phone takes the PB Vision app straight to its camera, and the recording
+uploads to that video. Anyone can record from the link, whether or not they
+are signed in to PB Vision.
+
+A typical event goes like this:
+
+1. **Create a folder for the event** with `getOrCreateFolder()`, using a name
+   that is unique to the event (see [Folders](#folders)).
+2. **Make a recording link for each game** with `makeRecordingLink()`, putting
+   the game in the event's folder and naming its players so they are
+   [tagged automatically](#auto-tagging-players).
+3. **Share the folder**: make it public with `updateFolder()` and send out the
+   link from `getPublicFolderUrl()`.
+
+```javascript
+import { PBVision } from '@pbvision/partner-sdk';
+
+const pbv = new PBVision(YOUR_API_KEY, { useProdServer: true });
+
+// 1. one folder per event
+const { fid } = await pbv.getOrCreateFolder('Spring Open 2026-04-18');
+
+// 2. one recording link per game
+const { vid, url } = await pbv.makeRecordingLink({
+  name: 'Spring Open, Court 3, Round 1',
+  fid,
+  court: '3',
+  playersForTagging: {
+    server: { name: 'Alice', email: 'alice@example.com' },
+    serverPartner: { name: 'Carol' },
+    receiver: { name: 'Bob', email: 'bob@example.com' },
+    receiverPartner: { name: 'Dave' }
+  }
+});
+// save `vid` with the game in your own records
+// show `url` as a QR code, or send it to whoever is recording the game
+
+// 3. share the event
+await pbv.updateFolder(fid, { public: true });
+const eventUrl = pbv.getPublicFolderUrl(fid);
+```
+
+`makeRecordingLink()` returns the new video's `vid`, your `uid`, and the `url`
+to share. It takes the same metadata as the other methods except
+`gameStartEpoch`: the game's time comes from its recording, and a time given
+in advance would override it, so passing one throws an error. It also throws
+if the account paying for the video can't pay for it (`hasCredits` is
+`false`).
+
+**One link per game.** If several people may ask for the same game's link (for
+example, any player on the court can tap "Record"), pass a `nonce` that
+identifies the game, such as your own ID for it. Every call with the same nonce
+returns the same video and link, even calls made at the same moment, and the
+first call decides the video's metadata. Until the video is uploaded, each call
+checks that the account paying for it can still pay; a call that can't gets no
+video and throws, and a later call gets the same video once the account can pay.
+`makeVideoId()` takes a `nonce` too (it returns `hasCredits: false` instead of
+throwing).
+
+```javascript
+const { url } = await pbv.makeRecordingLink({ nonce: `${eventId}-${gameId}`, fid, playersForTagging });
 ```
 
-### Video Editors
+**Camera settings.** By default the link records at 1080p and 30 FPS, and the
+person recording can't change either. Ask for 4K with `resolution: '4k'` or
+60 FPS with `fps: 60`, and let the person recording choose with
+`mayChangeResolution: true` and `mayChangeFPS: true`. 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.
+
+```javascript
+const { url } = await pbv.makeRecordingLink({
+  fid,
+  resolution: '4k',          // '1080p' (default) or '4k'
+  fps: 60,                   // 30 (default) or 60
+  mayChangeResolution: true, // default false
+  mayChangeFPS: false        // default false
+});
+```
 
-Editors can tag themselves and friends in the video. They also have access to
-the video even if the video is private (to make videos uploaded by your partner
-account private by default, please let us know via email).
+**One recording per link.** Only the first upload to a link's video counts, so
+make a new link for each game.
 
-You can get the current list of editors on a video by using the `getVideoEditors()`
-method. Similarly, the `setVideoEditors()` method can be used to change the
-email addresses which have editor access on your video.
+**Opening the link.** The PB Vision app opens only when the phone itself opens
+the link: when someone taps it (in a text message or an email, for example) or
+scans it as a QR code with the camera, or when your own app hands it to the
+operating system (for example with `UIApplication.shared.open()` on iOS or an
+`ACTION_VIEW` intent on Android). Don't load the link inside a webview or an
+in-app browser, where the app may not open. On a phone without the PB Vision
+app, the link shows a page for installing it.
+
+**Testing.** With the test server (`useProdServer: false`), links start with
+`pbvision://record` instead of `https://pb.vision/record`. Any installed PB
+Vision app opens them, so test on a phone with a development build of the app.
+The App Store or Google Play app would upload the recording to production,
+where the test video doesn't exist, and the recording would be lost.
+
+### Video Editors and Viewers
+
+Editors can tag themselves and friends in the video. Viewers have read-only
+access. Both editors and viewers can access the video even if it is private (to
+make videos uploaded by your partner account private by default, please let us
+know via email).
+
+You can get the current list of editors on a video using `getVideoEditors()`.
+Use `setVideoEditors()` to set both editor and viewer access (up to 8 emails
+each). Note that `setVideoEditors()` _replaces_ the existing editors and
+viewers lists entirely.
+
+```javascript
+// Get current editors
+const editors = await pbv.getVideoEditors(vid);
+
+// Set editors and viewers (replaces any previous lists)
+await pbv.setVideoEditors(
+  vid,
+  ['editor1@example.com', 'editor2@example.com'],  // editors
+  ['viewer1@example.com']                           // viewers
+);
+```
 
 ## After Video Processing is Done
 
@@ -170,10 +432,95 @@ data is enabled for your API key, only some of these fields may be present):
 - only included if `insights` is included:
   - `vid` - the unique ID of the video in our system
   - `aiEngineVersion` - the version number of our AI used to process the video
-  - Using these two values, you can retrieve the player thumbnail images extracted from the video like: `https://storage.googleapis.com/pbv-pro/${vid}/${aiEngineVersion}/player${playerIndex}-${imageIndex}.jpg` where `playerIndex` is in the range [0, 3] (for doubles games) and `imageIndex` is in the range [0, 7].
+
+### Fetching Insights by Video ID
+
+If you need to retrieve the insights data outside of the webhook callback (for
+example, to re-fetch data for a previously processed video), you can use a
+simple HTTP GET request with the video ID:
+
+```bash
+curl https://api-2o2klzx4pa-uc.a.run.app/video/VIDEO_ID/insights.json
+```
+
+Webhook callbacks with `include.insights` receive the raw insights JSON from
+storage. This endpoint is a separate convenience endpoint; by default, it
+returns a compact representation of the same session data. Add
+`?format=augmented` for readable field names:
+
+```bash
+curl 'https://api-2o2klzx4pa-uc.a.run.app/video/VIDEO_ID/insights.json?format=augmented'
+```
+
+For multi-game videos, pass the 1-indexed session number:
+
+```bash
+curl 'https://api-2o2klzx4pa-uc.a.run.app/video/VIDEO_ID/insights.json?sessionNum=2&format=augmented'
+```
+
+You can call this endpoint as many times as needed.
+
+### Player Identification
+
+PB Vision assigns each detected player an index based on visual detection.
+Players are indexed 0-3 for doubles (0-1 on one team, 2-3 on the other) and
+0 and 2 for singles. These indices are consistent _within_ a single video but
+do not carry over between videos, so "Player 0" in one video is not necessarily
+the same person as "Player 0" in another.
+
+**Player thumbnails** are available after processing. Using the `vid` and
+`aiEngineVersion` from the webhook callback, you can fetch thumbnail images for
+each player:
+
+```
+https://storage.googleapis.com/pbv-pro/{vid}/{aiEngineVersion}/player{playerIndex}-{imageIndex}.jpg
+```
+
+- `playerIndex`: 0-3 for doubles, 0 and 2 for singles
+- `imageIndex`: 0-7 (up to 8 thumbnails per player, captured at different
+  points in the game)
+
+For example, to get thumbnails for all four players in a doubles game:
+
+```
+https://storage.googleapis.com/pbv-pro/83gyqyc10y8f/7/player0-0.jpg
+https://storage.googleapis.com/pbv-pro/83gyqyc10y8f/7/player1-0.jpg
+https://storage.googleapis.com/pbv-pro/83gyqyc10y8f/7/player2-0.jpg
+https://storage.googleapis.com/pbv-pro/83gyqyc10y8f/7/player3-0.jpg
+```
+
+**Mapping players to your system:** If your integration needs to know which
+player is which (e.g. linking game stats to player profiles in your app), you
+have a few options:
+
+1. **Pass player emails at upload time** via the `userEmails` metadata field.
+   If you know which players are in the match, their emails will be associated
+   with the video as editors, and you can match them against your records.
+   Note that providing an email associates the video with that PB Vision
+   account, but it does not automatically identify which of the detected
+   players (`avatar_id`) belongs to that email. That mapping happens on
+   your side using the thumbnails or webpage link below.
+
+2. **Use thumbnails for manual or automated matching.** After processing, fetch
+   the player thumbnails and either surface them in an admin UI for manual
+   confirmation, or compare them against known player photos programmatically.
+   If thumbnails alone aren't enough, show the PB Vision `webpage` link next
+   to the avatar choices (or embed it in an iframe) so the user can reference
+   the video before selecting themselves.
+
+3. **Store your own metadata alongside the video ID.** When you upload a video,
+   record the returned `vid` alongside whatever context you have (match ID,
+   player roster, season, week, etc.) in your own system. When the webhook
+   fires, use the `vid` to look up that context and route the results
+   accordingly.
+
+The insights JSON also includes an `avatar_id` for each player, which
+corresponds to the `playerIndex` used in the thumbnail URLs above.
 
 ## Video Guidelines
 
+Note: We are now able to split videos into individual games if you'd like to upload more than one game per video. Let us know if this applies to your use case.
+
 Requirements:
 
 - Comply with [PB Vision's framing guidelines](https://help.pb.vision/en/help/articles/1108176-video-recording-and-framing-tips)

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.13",
+  "version": "0.1.15",
   "license": "MIT",
   "type": "module",
   "engines": {

package/src/index.js

@@ -3,9 +3,38 @@ import fs from 'node:fs'
 
 import fetch from 'node-fetch'
 
+// sent with each new video so PB Vision knows which version of this SDK made
+// it. Read lazily and forgivingly: an app bundled with a tool like esbuild may
+// not ship this package's package.json, or may ship its own in its place.
+let platform
+function getPlatform () {
+  if (!platform) {
+    let version = 'unknown'
+    try {
+      const pkg = JSON.parse(
+        fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+      if (pkg.name === '@pbvision/partner-sdk' && pkg.version) {
+        version = pkg.version
+      }
+    } catch {
+      // keep 'unknown'
+    }
+    platform = { name: 'api', version }
+  }
+  return platform
+}
+
+// the camera settings a recording link may ask the PB Vision app for
+const RECORDING_RESOLUTIONS = ['1080p', '4k']
+const RECORDING_FPS = [30, 60]
+
 const ENVIRONMENTS = {
   test: {
     apiServer: 'https://api-ko3kowqi6a-uc.a.run.app',
+    webApp: 'https://pbv-dev.web.app',
+    // development builds of the PB Vision app can't open https links, so test
+    // links use the app's own scheme, which store builds open too
+    recordLink: 'pbvision://record',
     firebaseConfig: {
       apiKey: 'AIzaSyCV1uh4fM7IFopuZOJ306oVWLV3cKLijFc',
       projectId: 'pbv-dev',
@@ -14,6 +43,8 @@ const ENVIRONMENTS = {
   },
   prod: {
     apiServer: 'https://api-2o2klzx4pa-uc.a.run.app',
+    webApp: 'https://pb.vision',
+    recordLink: 'https://pb.vision/record',
     firebaseConfig: {
       apiKey: 'AIzaSyCzC8mfo38HtkOR-_Y6xb7Pevp72LkrYfc',
       projectId: 'pbv-prod',
@@ -32,6 +63,8 @@ export class PBVision {
     this.uid = apiKey.substring(0, underscoreIndex)
     const config = useProdServer ? ENVIRONMENTS.prod : ENVIRONMENTS.test
     this.server = config.apiServer
+    this.webAppUrl = config.webApp
+    this.recordUrl = config.recordLink
     this.isDev = config === ENVIRONMENTS.test
   }
 
@@ -86,13 +119,13 @@ export class PBVision {
    * @param {VideoMetadata} [metadata]
    * @returns {VideoUrlToDownloadResponse}
    */
-  async sendVideoUrlToDownload (videoUrl, { userEmails = [], name, desc, gameStartEpoch, facility, court, fid } = {}) {
+  async sendVideoUrlToDownload (videoUrl, { userEmails = [], name, desc, gameStartEpoch, facility, court, fid, 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')
     const resp = await this.__callAPI(
       'add_video_by_url',
-      { url: videoUrl, userEmails, name, desc, gameStartEpoch, facility, court, fid })
+      { url: videoUrl, userEmails, name, desc, gameStartEpoch, facility, court, fid, playersForTagging })
     return JSON.parse(resp)
   }
 
@@ -126,94 +159,455 @@ export class PBVision {
    * @property {integer} [gameStartEpoch] the epoch at which the game started
    * @property {string} [facility] the facility where the game was recorded (e.g., "Cool Club #3 - Barcelona")
    * @property {string} [court] the court where the game was recorded (e.g., "11A")
-   * @property {integer} [fid] the ID of the folder in which this video should be added
+   * @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 {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.
+   *   Honored by uploadVideo(), sendVideoUrlToDownload(), makeVideoId(), and
+   *   makeRecordingLink().
+   */
+
+  /**
+   * The players to tag automatically once the video is processed, identified
+   * by their role at the start of the first game. The team that serves first
+   * supplies `server` (its first server) and `serverPartner`. The other team's
+   * first server is `receiver`: they start on the right and receive the first
+   * serve. Their partner is `receiverPartner`. Omit both partners for singles.
+   * Each email may be given for only one player.
+   * @typedef {Object} PlayersForTagging
+   * @property {PlayerForTagging} server the player who served the first point
+   * @property {PlayerForTagging} receiver the player who received the first point
+   * @property {PlayerForTagging} [serverPartner] the server's partner (omit for singles)
+   * @property {PlayerForTagging} [receiverPartner] the receiver's partner (omit for singles)
+   */
+
+  /**
+   * A player to tag, identified by a name, an email, or both. At least one of
+   * the two is required.
+   * @typedef {Object} PlayerForTagging
+   * @property {string} [name] what to call the player: 1 to 64 characters
+   *   after trimming. Shown unless the email belongs to a PB Vision account,
+   *   in which case that account's own name is shown.
+   * @property {string} [email] the player's email address. The player is
+   *   emailed that they were tagged. If the address belongs to a PB Vision
+   *   account, the game is added to that account's library; if not, the game
+   *   joins their library when they sign up with this address.
+   */
+
+  /**
+   * Allocate a new video ID *without* uploading a file yourself. Useful when the
+   * video will be recorded and uploaded by another client. Pass the returned
+   * `vid` (and `uid`) to that client so it uploads to this video instead of
+   * allocating a new one. To have the game recorded with the PB Vision app,
+   * use makeRecordingLink() instead.
+   *
+   * @param {VideoMetadata} [metadata] the video's metadata, plus fileExt
+   * @param {string} [metadata.fileExt="mp4"] the extension the video will be
+   *   uploaded with
+   * @param {string} [metadata.nonce] 1 to 200 characters you choose, such as
+   *   your own ID for the game. Every call with the same nonce gets the same
+   *   video, even calls made at the same moment; the first call decides its
+   *   metadata. Until the video is uploaded, each call checks that the account
+   *   paying for it can still pay; if not, that call gets no video (`hasCredits`
+   *   false), and a later call gets the same video once it can. A call that
+   *   gets no video doesn't use the nonce up.
+   * @returns {{vid: (string|undefined), uid: string, hasCredits: (boolean|undefined)}}
+   *   the new video id and the uid it belongs to. `hasCredits` is false, with
+   *   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 } = {}) {
+    const resp = await this.__callAPI('make_video_id',
+      { platform: getPlatform(), fileExt, userEmails, name, desc, gameStartEpoch, facility, court, fid, playersForTagging, nonce })
+    const { hasCredits, vid } = JSON.parse(resp)
+    const ret = { vid, uid: this.uid }
+    if (hasCredits !== undefined) {
+      ret.hasCredits = hasCredits
+    }
+    return ret
+  }
+
+  /**
+   * The video's details and camera settings for makeRecordingLink(). The
+   * details are the same as in VideoMetadata, except that there is no
+   * gameStartEpoch: the game's time comes from its recording.
+   * @typedef {Object} RecordingLinkOptions
+   * @property {Array<string>} [userEmails] the email addresses of up to 4
+   *   players in the game (see VideoMetadata)
+   * @property {string} [name] the title of the game
+   * @property {string} [desc] a longer description of the game
+   * @property {string} [facility] the facility where the game is played
+   * @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 {PlayersForTagging} [playersForTagging] the players to tag
+   *   automatically once processing completes
+   * @property {string} [nonce] identifies the game, e.g. your own ID for it:
+   *   every call with the same nonce returns the same video and link (see
+   *   makeVideoId())
+   * @property {string} [resolution='1080p'] the resolution to record at:
+   *   '1080p' or '4k'. 4K requires your partner account to have 4K enabled;
+   *   otherwise PB Vision rejects the upload.
+   * @property {integer} [fps=30] the frame rate to record at: 30 or 60
+   * @property {boolean} [mayChangeResolution=false] whether the person
+   *   recording may choose a different resolution in the app
+   * @property {boolean} [mayChangeFPS=false] whether the person recording may
+   *   choose a different frame rate in the app
+   */
+
+  /**
+   * @typedef {Object} RecordingLink
+   * @property {string} vid the ID of the video the recording will upload to
+   * @property {string} uid the ID of your partner account, which owns the video
+   * @property {string} url the link that opens the PB Vision app to record the
+   *   game
    */
 
+  /**
+   * Makes a video for a game and a link that opens the PB Vision app on a
+   * phone straight to its camera, to record the game into that video. Anyone
+   * can record from the link, signed in to PB Vision or not. On a phone
+   * without the app, the link shows a page for installing it.
+   *
+   * 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.
+   *
+   * 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
+   * the same game's link, pass the same `nonce` (e.g. your own ID for the
+   * game) and they all get one video and one link.
+   *
+   * Open the link with a real tap (e.g. in a text message, an email, or a
+   * scanned QR code) or by handing it to the phone's operating system, not
+   * inside a webview, so that the phone can open the PB Vision app.
+   *
+   * With the test server (`useProdServer: false`), the link starts with
+   * `pbvision://record`. Any installed PB Vision app opens it, so test with a
+   * development build of the app: the App Store or Google Play app would
+   * upload the recording to production, where the test video doesn't exist,
+   * and the recording would be lost.
+   *
+   * @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)
+   */
+  async makeRecordingLink ({
+    resolution = '1080p', fps = 30, mayChangeResolution = false, mayChangeFPS = false,
+    gameStartEpoch, userEmails, name, desc, facility, court, fid, 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')
+    assert(RECORDING_RESOLUTIONS.includes(resolution),
+      `resolution must be '1080p' or '4k', not ${JSON.stringify(resolution)}`)
+    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')
+
+    const { vid, uid, hasCredits } = await this.makeVideoId({
+      fileExt: 'mp4', userEmails, name, desc, facility, court, fid, 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)')
+    }
+    if (!vid) {
+      throw new Error('PB Vision did not return a video ID for this recording link')
+    }
+    // encodeURIComponent() rather than URLSearchParams, which writes a space
+    // as "+" and not every app reads that back as a space
+    const query = Object.entries({ vid, uid, resolution, fps, mayChangeResolution, mayChangeFPS })
+      .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
+      .join('&')
+    return { vid, uid, url: `${this.recordUrl}?${query}` }
+  }
+
   /**
    * Upload a video for processing by the AI.
    *
-   * For passthrough partners, the video is only uploaded if the paying user
-   * has credit(s) available with which the video can be analyzed.
+   * The video is only uploaded if the account paying for it has credit(s)
+   * available with which the video can be analyzed. If not, nothing is
+   * uploaded and this returns `{ hasCredits: false }` with no `vid`.
+   *
+   * The upload resumes by itself after a dropped connection or a temporary
+   * error from the storage service. If it still fails, the error thrown has
+   * the video's ID as its `vid` property. To retry without making a second
+   * video for the game, pass a `nonce` (see makeVideoId()): calling this again
+   * with the same nonce uploads to the same video.
    *
    * @param {string} mp4Filename
    * @param {VideoMetadata} [metadata]
    * @returns {VideoUrlToDownloadResponse}
+   * @throws {Error} if the upload fails, with the video's ID as `vid`. A
+   *   missing or empty file is refused before any video is made.
    */
-  async uploadVideo (mp4Filename, { userEmails = [], name, desc, gameStartEpoch, facility, court, fid } = {}) {
+  async uploadVideo (mp4Filename, metadata = {}) {
+    // checked before making the video, so a file that can't be uploaded
+    // doesn't leave a video behind that never gets one
+    const stats = await fs.promises.stat(mp4Filename)
+    assert(stats.isFile(), `cannot upload ${mp4Filename}: it is not a file`)
+    assert(stats.size > 0, `cannot upload ${mp4Filename}: the file is empty`)
     const pieces = mp4Filename.split('.')
     const ext = pieces[pieces.length - 1]
-    const platform = { name: 'api', version: '0.1.12' }
-    const makeVIDResp = await this.__callAPI('make_video_id', { platform, userEmails, name, desc, gameStartEpoch, facility, court, fid, fileExt: ext })
-    const { hasCredits, vid } = JSON.parse(makeVIDResp)
+    const { hasCredits, vid } = await this.makeVideoId({ ...metadata, fileExt: ext })
     if (hasCredits === false) {
       return { hasCredits }
     }
     const bucket = `pbv-uploads${this.isDev ? '-dev' : ''}`
     const objName = `${this.uid}/${vid}.${ext}`
-    await uploadToGCS(bucket, objName, mp4Filename)
+    try {
+      await uploadToGCS(bucket, objName, mp4Filename)
+    } catch (e) {
+      const err = new Error(`PB Vision Upload of video ${vid} failed: ${e.message}`, { cause: e })
+      err.vid = vid
+      throw err
+    }
     const ret = { vid }
     if (hasCredits !== undefined) {
       ret.hasCredits = hasCredits
     }
     return ret
   }
+
+  /**
+   * @typedef {Object} GetOrCreateFolderResponse
+   * @property {integer} fid the folder's ID; pass it as the `fid` metadata
+   *   field to put a new video in this folder
+   * @property {boolean} created true if this call created the folder, false if
+   *   it already existed
+   */
+
+  /**
+   * Gets the folder in your partner account's library with exactly this name,
+   * creating it if there is none. Calling it again with the same name returns
+   * the same folder, as long as it hasn't been renamed or moved since, so it
+   * is safe to retry.
+   *
+   * Use a unique name for each event, such as one that includes its date;
+   * otherwise two events with the same name would share one folder.
+   *
+   * @param {string} name the folder's name: 1 to 200 characters, with no
+   *   leading or trailing whitespace
+   * @param {Object} [options]
+   * @param {integer} [options.parent] the ID of the folder to look in, and to
+   *   create the folder in; omit for the top level of your library
+   * @returns {GetOrCreateFolderResponse}
+   */
+  async getOrCreateFolder (name, { parent } = {}) {
+    const resp = await this.__callAPI('folder/get_or_create', { name, parent })
+    const { fid, created } = JSON.parse(resp)
+    return { fid, created }
+  }
+
+  /**
+   * Renames a folder in your partner account's library, moves it, or changes
+   * whether it is public. Fields you omit are left as they are.
+   *
+   * @param {integer} fid the ID of the folder to change
+   * @param {Object} [changes]
+   * @param {string} [changes.name] the folder's new name: 1 to 200 characters,
+   *   with no leading or trailing whitespace
+   * @param {?integer} [changes.parent] the ID of the folder to move it into, or
+   *   null to move it to the top level of your library
+   * @param {boolean} [changes.public] whether anyone with the folder's link may
+   *   view it, signed in or not (see getPublicFolderUrl()). A folder inside a
+   *   public folder is only shown with it if it is public too.
+   */
+  async updateFolder (fid, { name, parent, public: isPublic } = {}) {
+    await this.__callAPI('folder/update', { fid, name, parent, public: isPublic })
+  }
+
+  /**
+   * The link to a folder's page on PB Vision, where anyone can view its videos
+   * once the folder is public (see updateFolder()).
+   *
+   * @param {integer} fid the folder's ID
+   * @returns {string}
+   */
+  getPublicFolderUrl (fid) {
+    assert(Number.isInteger(fid) && fid > 0, `invalid folder ID: ${fid}`)
+    return `${this.webAppUrl}/library/public/${encodeURIComponent(this.uid)}/${fid}`
+  }
 }
 
+// How uploadToGCS() reads and sends the file: one chunk in memory at a time.
+// GCS needs every chunk but the last to be a multiple of 256 KiB; larger
+// chunks tend to upload faster but take more memory.
+const UPLOAD_CHUNK_SIZE = 8 * 1024 * 1024
+
+// How uploadToGCS() retries a request that fails with a network error or a
+// temporary server error: up to UPLOAD_MAX_RETRIES times in a row without the
+// upload making progress, waiting about twice as long before each retry, up to
+// UPLOAD_MAX_RETRY_DELAY_MS (plus up to a second at random).
+const UPLOAD_MAX_RETRIES = 6
+const UPLOAD_FIRST_RETRY_DELAY_MS = 1000
+const UPLOAD_MAX_RETRY_DELAY_MS = 32000
+
+// Uploads a file to GCS with a resumable upload, following GCS's protocol: a
+// 308 response says how much GCS has stored so far (its Range header), and the
+// upload is only done once GCS answers 200 or 201. After a network error or a
+// temporary server error, it waits, asks GCS how much it has stored, and goes
+// on from there. Throws an Error saying why if the upload fails.
 async function uploadToGCS (bucket, objName, filename) {
-  // request to start a new upload
+  const file = await fs.promises.open(filename, 'r')
+  try {
+    const { size: numBytesTotal } = await file.stat()
+    if (numBytesTotal === 0) {
+      throw new Error('the file is empty') // it was emptied after it was checked
+    }
+    const sessionURI = await startResumableUpload(bucket, objName, numBytesTotal)
+
+    let offset = 0 // how many bytes GCS has stored
+    let failures = 0 // tries in a row which made no progress
+    let mustAskOffset = false // whether to ask GCS for the offset before sending
+    for (;;) {
+      let request, action
+      if (mustAskOffset) {
+        action = 'checking the upload\'s progress'
+        request = {
+          method: 'PUT',
+          headers: { 'Content-Length': '0', 'Content-Range': `bytes */${numBytesTotal}` }
+        }
+      } else {
+        const endIdx = Math.min(offset + UPLOAD_CHUNK_SIZE, numBytesTotal) - 1
+        action = `uploading bytes ${offset}-${endIdx}`
+        // a file that can't be read is not worth retrying, so this throws
+        const chunk = await readChunk(file, offset, endIdx - offset + 1, numBytesTotal)
+        request = {
+          method: 'PUT',
+          headers: {
+            'Content-Length': String(chunk.length),
+            'Content-Range': `bytes ${offset}-${endIdx}/${numBytesTotal}`
+          },
+          body: chunk
+        }
+      }
+
+      let resp, respBody, problem
+      try {
+        resp = await fetch(sessionURI, request)
+        respBody = await resp.text()
+      } catch (e) {
+        // even a 200 whose body was cut off is confirmed by asking GCS
+        resp = undefined
+        problem = `network error while ${action}: ${e.message}`
+      }
+
+      if (resp && (resp.status === 200 || resp.status === 201)) {
+        return
+      }
+      if (resp?.status === 308) {
+        const stored = parseStoredRange(resp.headers.get('Range'), numBytesTotal)
+        if (stored === numBytesTotal) {
+          throw new Error(`GCS stored all ${numBytesTotal} bytes but did not finish the upload (308)`)
+        }
+        const madeProgress = stored > offset
+        const wasAsking = mustAskOffset
+        problem = `GCS stored nothing more while ${action} (308, offset ${stored})`
+        offset = stored
+        mustAskOffset = false
+        if (madeProgress) {
+          failures = 0
+          continue
+        }
+        if (wasAsking) {
+          continue // the failure that made us ask was already counted
+        }
+        // GCS kept none of the chunk: resend it, after a wait
+      } else if (resp && !isTemporaryStatus(resp.status)) {
+        if (mustAskOffset && (resp.status === 404 || resp.status === 410)) {
+          throw new Error(`the upload session expired (${resp.status}): ${respBody}`)
+        }
+        throw new Error(`GCS answered ${resp.status} while ${action}: ${respBody}`)
+      } else {
+        problem ??= `GCS answered ${resp.status} while ${action}: ${respBody}`
+        mustAskOffset = true
+      }
+
+      failures++
+      if (failures > UPLOAD_MAX_RETRIES) {
+        throw new Error(`gave up after ${UPLOAD_MAX_RETRIES} retries; last error: ${problem}`)
+      }
+      await waitBeforeRetry(failures)
+    }
+  } finally {
+    await file.close()
+  }
+}
+
+// Starts a resumable upload and returns its session URI.
+async function startResumableUpload (bucket, objName, numBytesTotal) {
   const url = `https://storage.googleapis.com/upload/storage/v1/b/${bucket}/o?uploadType=resumable&name=${objName}`
-  const numBytesTotal = fs.statSync(filename).size
-  let headers = { 'X-Upload-Content-Length': numBytesTotal }
-  let resp = await fetch(url, { method: 'POST', headers })
-  if (!resp.ok) {
-    throw new Error(`PB Vision Upload failed to initialize (${resp.status}): ${await resp.text()}`)
-  }
-  const sessionURI = resp.headers.get('Location')
-
-  // determine how much data to read from the file at once; larger tends to
-  // result in faster uploads but also has a bigger memory footprint
-  const minChunkSz = 256 * 1024 // this is the *minimum* size
-  const targetChunkSzMB = 8
-  const chunkSize = Math.max(minChunkSz, targetChunkSzMB * 1024 * 1024)
-
-  // upload one chunk at a time until it is done successfully
-  let startIdx = 0
-  while (startIdx < numBytesTotal) {
-    let endIdx = startIdx + chunkSize - 1
-    endIdx = Math.min(endIdx, numBytesTotal - 1)
-    const thisChunkSize = endIdx - startIdx + 1
-
-    // read just the chunk we need from the file
-    const streamPromise = new Promise((resolve, reject) => {
-      const chunk = Buffer.alloc(thisChunkSize)
-      let chunkBytesRead = 0
-      const stream = fs.createReadStream(
-        filename, { start: startIdx, end: endIdx })
-      stream.on('data', x => {
-        x.copy(chunk, chunkBytesRead)
-        chunkBytesRead += x.length
-      })
-      stream.on('end', () => resolve(chunk))
-      stream.on('error', e => reject(e))
-    })
-    let chunk
+  for (let failures = 0; ; failures++) {
+    let resp, respBody, problem
     try {
-      chunk = await streamPromise
+      resp = await fetch(url, {
+        method: 'POST',
+        headers: { 'X-Upload-Content-Length': String(numBytesTotal) }
+      })
+      respBody = await resp.text()
     } catch (e) {
-      throw new Error(`PB Vision Upload failed to read from file ${e.toString()}`)
+      problem = `network error while initializing: ${e.message}`
     }
-
-    headers = {
-      'Content-Length': chunk.length,
-      'Content-Range': `bytes ${startIdx}-${endIdx}/${numBytesTotal}`
+    if (resp?.ok) {
+      const sessionURI = resp.headers.get('Location')
+      if (!sessionURI) {
+        throw new Error('GCS started the upload but gave no session URI')
+      }
+      return sessionURI
+    }
+    if (resp && !isTemporaryStatus(resp.status)) {
+      throw new Error(`failed to initialize (${resp.status}): ${respBody}`)
+    }
+    problem ??= `GCS answered ${resp.status} while initializing: ${respBody}`
+    if (failures >= UPLOAD_MAX_RETRIES) {
+      throw new Error(`gave up after ${UPLOAD_MAX_RETRIES} retries; last error: ${problem}`)
     }
-    assert(chunk.length <= numBytesTotal)
-    assert(chunk.length === endIdx - startIdx + 1)
-    resp = await fetch(sessionURI, { method: 'PUT', headers, body: chunk })
-    if (!resp.status >= 400) {
-      throw new Error(`PB Vision Upload failed to upload chunk ${startIdx} (${resp.status}): ${await resp.text()} ${JSON.stringify(resp.headers.raw())}`)
+    await waitBeforeRetry(failures + 1)
+  }
+}
+
+// GCS asks clients to retry these, with exponential backoff
+function isTemporaryStatus (status) {
+  return status >= 500 || status === 408 || status === 429
+}
+
+async function waitBeforeRetry (retryNumber) {
+  const delayMs = Math.min(
+    UPLOAD_FIRST_RETRY_DELAY_MS * 2 ** (retryNumber - 1), UPLOAD_MAX_RETRY_DELAY_MS)
+  await new Promise(resolve => setTimeout(resolve, delayMs + Math.random() * 1000))
+}
+
+// Returns how many bytes a 308's Range header (e.g. "bytes=0-1048575") says
+// GCS has stored; no Range header means none.
+function parseStoredRange (range, numBytesTotal) {
+  if (range === null) {
+    return 0
+  }
+  const match = /^bytes=0-(\d+)$/.exec(range)
+  const stored = match ? Number(match[1]) + 1 : NaN
+  if (!(stored <= numBytesTotal)) {
+    throw new Error(`GCS sent an unexpected Range header: ${range}`)
+  }
+  return stored
+}
+
+// Reads length bytes of the file, starting at position.
+async function readChunk (file, position, length, numBytesTotal) {
+  const chunk = Buffer.alloc(length)
+  let chunkBytesRead = 0
+  while (chunkBytesRead < length) {
+    const { bytesRead } = await file.read(
+      chunk, chunkBytesRead, length - chunkBytesRead, position + chunkBytesRead)
+    if (bytesRead === 0) {
+      throw new Error(`the file ended at byte ${position + chunkBytesRead}, before the ${numBytesTotal} bytes it had when the upload started`)
     }
-    startIdx = endIdx + 1
+    chunkBytesRead += bytesRead
   }
-  return true
+  return chunk
 }