@pbvision/partner-sdk 0.0.1 → 0.0.3

package/README.md

@@ -4,22 +4,43 @@ 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 an hour for a
 standard length game, so we'll notify your servers when the results are ready.
 
-- [Using the API](#using-the-api)
+- [Installation](#installation)
   - [Step 1: Get API Access](#step-1-get-api-access)
-  - [Step 2: Webhook Setup](#step-2-webhook-setup)
-  - [Step 3: Send Videos](#step-3-send-videos)
-  - [Step 4: Video Processing Done](#step-4-video-processing-done)
-- [SDK Setup](#sdk-setup)
+  - [Step 2: SDK Setup](#step-2-sdk-setup)
+- [Using the API](#using-the-api)
+  - [Webhook Setup](#webhook-setup)
+  - [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)
+- [After Video Processing is Done](#after-video-processing-is-done)
 - [Video Guidelines](#video-guidelines)
+- [Reference Guide](#reference-guide)
 
-## Using the API
+## Installation
 
 ### Step 1: Get API Access
 
 Email **[dev@pb.vision](mailto:dev@pb.vision)** to request API access for your
 account. We'll send you an API Key.
 
-### Step 2: Webhook Setup
+### Step 2: SDK Setup
+
+1. Install [node](https://nodejs.org/en/download)
+2. Install the SDK: `npm i @pbvision/partner-sdk`
+3. In your package.json, make sure you're configured to use ESM (modules): `"type": "module"`
+4. Initialize the SDK:
+
+```javascript
+import { PBVision } from '@pbvision/partner-sdk'
+const pbv = new PBVision(YOUR_API_KEY)
+```
+
+5. Use its methods as described to [send us video URLs](#send-videos) to
+   to process, or [tell us your webhook's URL](#webhook-setup).
+
+## Using the API
+
+### Webhook Setup
 
 Each time our AI finishes processing a video, it will notify your servers via
 an HTTP POST request to a URL ("webhook") of your choice. You can use our SDK
@@ -42,7 +63,9 @@ curl -X POST \
      https://api-ko3kowqi6a-uc.a.run.app/partner/webhook/set
 ```
 
-### Step 3: Send Videos
+### Send Videos
+
+#### Option 1: PBV Downloads your video from a URL
 
 First, upload a video to a _publicly_ accessible URL on your server. For best
 results, videos should follow our [guidelines](#video-guidelines).
@@ -53,8 +76,8 @@ 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)
-const playerEmails = [] // optional!
-await pbv.sendVideoUrlToDownload(YOUR_VIDEO_URL, playerEmails)
+const userEmails = [] // optional!
+await pbv.sendVideoUrlToDownload(YOUR_VIDEO_URL, userEmails)
 ```
 
 Alternatively, you can just use `curl`:
@@ -67,12 +90,30 @@ curl -X POST \
      https://api-ko3kowqi6a-uc.a.run.app/partner/add_video_by_url
 ```
 
-### Step 4: Video Processing Done
+#### Option 2: Upload your video
+
+You can directly upload your video from a file using the SDK too:
+
+```javascript
+import { PBVision } from '@pbvision/partner-sdk'
+
+const pbv = new PBVision(YOUR_API_KEY)
+// you can omit this metadata, or provide it-- whatever you'd like!
+const optionalMetadata = {
+  userEmails: [],
+  name: 'Dink Championship 2024',
+  desc: 'A longer description, if you want',
+  gameStartEpoch: 1711393200 // when the game was played
+}
+await pbv.uploadVideo(YOUR_VIDEO_FILENAME, optionalMetadata)
+```
+
+## After Video Processing is Done
 
 When our AI is done processing your video, we will email the players in the
 game (_if_ their email addresses were provided).
 
-If you provided a webhook in [step 2](#step-2-webhook-setup), then we'll send
+If you [provided a webhook](#webhook-setup), then we'll send
 an HTTP POST request to your server. Your server should acknowledge this
 callback with a standard 200 (OK) response. If it does not, we will attempt to
 retry sending this request later (up to some maximum number of attempts).
@@ -91,7 +132,7 @@ The HTTP POST body will contain JSON which looks like this:
 }
 ```
 
-- `from_url` is the video url you sent us in [step 3](#step-3-send-videos)
+- `from_url` is the video url you sent us in [step 3](#send-videos)
 - `webpage` is a link to our web app where the stats can be explored
 - `error` is only present if your video could not be processed
 - `events` - describes the pickleball game in detailed, low-level events
@@ -101,21 +142,6 @@ The HTTP POST body will contain JSON which looks like this:
   - Explore the _insights_ schema at <https://pbv-public.github.io/insights/dev>
   - Schema changes and diffs are in our [`pbv-public/insights` repo](https://github.com/pbv-public/insights/blob/dev/CHANGELOG.md)
 
-## SDK Setup
-
-1. Install [node](https://nodejs.org/en/download)
-2. Install the SDK: `npm i @pbvision/partner-sdk`
-3. In your package.json, make sure you're configured to use ESM (modules): `"type": "module"`
-4. Initialize the SDK:
-
-```javascript
-import { PBVision } from '@pbvision/partner-sdk'
-const pbv = new PBVision(YOUR_API_KEY)
-```
-
-5. Use its methods as described to [send us video URLs](#step-3-send-videos) to
-   to process, or [tell us your webhook's URL](#step-2-webhook-setup).
-
 ## Video Guidelines
 
 Requirements:
@@ -132,3 +158,7 @@ For best results, we also recommend:
 - Max bitrate: 2 Mbps
 - Max file size: 1GB
 - Max duration: 30 minutes
+
+## Reference Guide
+
+- [JSDocs](https://pbv-public.github.io/partner-sdk-nodejs/)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pbvision/partner-sdk",
   "description": "SDK for interacting with the PB Vision pickleball AI engine.",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -18,5 +18,8 @@
   "dependencies": {
     "node-fetch": "^3.3.2"
   },
-  "devDependencies": {}
+  "devDependencies": {
+    "jsdoc": "3.6.4",
+    "tui-jsdoc-template": "^1.2.2"
+  }
 }

package/src/index.js

@@ -1,14 +1,29 @@
 import assert from 'node:assert'
+import fs from 'node:fs'
 
+import { makeSignedGoogleCloudStorageVideoObjectName } from './video-object-name.js'
 import fetch from 'node-fetch'
 
+const ENVIRONMENTS = {
+  test: {
+    apiServer: 'https://api-ko3kowqi6a-uc.a.run.app',
+    firebaseConfig: {
+      apiKey: 'AIzaSyCV1uh4fM7IFopuZOJ306oVWLV3cKLijFc',
+      projectId: 'pbv-dev',
+      appId: '1:542837591762:web:06f45c0d7a7e62f25aa70b'
+    }
+  }
+}
+
+/** @public */
 export class PBVision {
-  constructor (apiKey, server = 'https://api-ko3kowqi6a-uc.a.run.app') {
+  constructor (apiKey, config = ENVIRONMENTS.test) {
     assert(apiKey && apiKey.length === 31 && apiKey.indexOf('_') === 10,
       `invalid API key: ${apiKey}`)
 
     this.apiKey = apiKey
-    this.server = server
+    this.server = config.apiServer
+    this.isDev = config === ENVIRONMENTS.test
   }
 
   /**
@@ -28,16 +43,14 @@ export class PBVision {
    * processing is complete, your webhook URL will receive a callback.
    *
    * @param {string} videoUrl the publicly available URL of the video
-   * @param {Array<string>} [playerEmails] the email addresses of players in
+   * @param {Array<string>} [userEmails] the email addresses of players in
    *   this video; they'll be notified when the video is done processing
-   * @returns
    */
-  async sendVideoUrlToDownload (videoUrl, playerEmails = []) {
+  async sendVideoUrlToDownload (videoUrl, userEmails = []) {
     assert(typeof videoUrl === 'string' && videoUrl.startsWith('http'),
       'URL must be a string beginning with http')
     assert(videoUrl.endsWith('.mp4'), 'video URL must have the .mp4 extension')
-    return this.__callAPI(
-      'add_video_by_url', { url: videoUrl, userEmails: playerEmails })
+    this.__callAPI('add_video_by_url', { url: videoUrl, userEmails })
   }
 
   async __callAPI (path, body) {
@@ -50,10 +63,114 @@ export class PBVision {
       compress: true,
       body: JSON.stringify(body)
     })
+    const respBody = await resp.text()
     if (resp.ok) {
-      return true
+      return respBody || true
+    }
+    throw new Error(`PB Vision API ${path} failed (${resp.status}): ${respBody}`)
+  }
+
+  /**
+   * Information about the Video that can be set prior to it being uploaded.
+   * @typedef {Object} VideoMetadata
+   * @property {Array<string>} userEmails a list of email addresses of up to 4
+   *   players who were playing in the game; they will also be notified when
+   *   the video processing is complete (unless they have these notifications
+   *   disabled)
+   * @property {string} [name] the title of the game (if omitted, we'll use the
+   *   time of the game, or if that isn't provided then the time of the upload)
+   * @property {string} [desc] a longer description of the game
+   * @property {integer} [gameStartEpoch] the epoch at which the game started
+   */
+
+  /**
+   * Upload a video for processing by the AI.
+   * @param {string} mp4Filename
+   * @param {VideoMetadata} [metadata]
+   * @returns {string} the full Google Cloud Storage filename which this was
+   *   uploaded to
+   */
+  async uploadVideo (mp4Filename, { userEmails = [], name, desc, gameStartEpoch } = {}) {
+    // get the upload signing key if we didn't get it earlier
+    if (!this.signingKey) {
+      this.signingKey = await this.__callAPI('get_signing_key')
+    }
+
+    // create a unique, signed upload name
+    const uid = this.apiKey.split('_')[0]
+    const bucket = `pbv-uploads${this.isDev ? '-dev' : ''}`
+    const objName = makeSignedGoogleCloudStorageVideoObjectName({
+      uploaderUID: uid,
+      signingKey: this.signingKey,
+      bucket
+    })
+
+    // if given extra information about this video, upload that first
+    if (userEmails.length || name || desc || gameStartEpoch) {
+      const body = { objName, userEmails, name, desc, gameStartEpoch }
+      await this.__callAPI('set_pre_upload_metadata', body)
+    }
+
+    await uploadToGCS(bucket, objName, mp4Filename)
+    return objName
+  }
+}
+
+async function uploadToGCS (bucket, objName, filename) {
+  // request to start a new upload
+  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
+    try {
+      chunk = await streamPromise
+    } catch (e) {
+      throw new Error(`PB Vision Upload failed to read from file ${e.toString()}`)
+    }
+
+    headers = {
+      'Content-Length': chunk.length,
+      'Content-Range': `bytes ${startIdx}-${endIdx}/${numBytesTotal}`
+    }
+    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())}`)
     }
-    const errBody = await resp.text()
-    throw new Error(`PB Vision API ${path} failed (${resp.status}): ${errBody}`)
+    startIdx = endIdx + 1
   }
+  return true
 }

package/src/video-object-name.js

@@ -0,0 +1,68 @@
+import assert from 'node:assert'
+import crypto from 'node:crypto'
+
+/**
+ * Creates the name for a video file to upload to our uploads bucket.
+ *
+ * The name is signed with the uploader's API Key to prove that the upload is
+ * indeed from them.
+ *
+ * The object name is formatted like:
+ * <User ID>/<Video ID>-<Security Hash>.<File Extension>
+ *
+ * @param {Object} opts information about the video upload
+ * @param {string} opts.uploaderUID the video uploader's user ID
+ * @param {string} opts.signingKey the video uploader's API Key
+ * @param {string} [opts.fileExt] the video's file extension
+ * @param {string} [opts.bucket] the GCS bucket to upload to
+ * @returns {string} the signed GCS object filename
+ * @protected
+ */
+export function makeSignedGoogleCloudStorageVideoObjectName ({
+  uploaderUID,
+  signingKey,
+  fileExt = 'mp4',
+  bucket = 'pbv-uploads',
+  uploadId = undefined
+}) {
+  assert(typeof uploaderUID === 'string' && uploaderUID.length)
+  assert(typeof signingKey === 'string' && signingKey.length)
+  uploadId = uploadId ?? crypto.randomUUID().replace(/-/g, '')
+  assert(typeof uploadId === 'string' && uploadId.length === 32)
+  return makeObjectName(uploaderUID, signingKey, uploadId, fileExt, bucket)
+}
+
+/**
+ * Returns the hash from the parameters used to construct a GCS object name.
+ *
+ * The hash includes all elements of the file's unique path (including the
+ * bucket) except for the hash itself.
+ * @private
+ */
+function getHash (uploaderUID, signingKey, uploadId, fileExt, bucket) {
+  const nameWithEmptyHash = makeObjectNameGivenHash(
+    uploaderUID, uploadId, fileExt, '')
+  return crypto.createHash('sha256')
+    .update(signingKey + bucket + nameWithEmptyHash)
+    .digest('hex')
+}
+
+/**
+ * Returns the full GCS object name (including hash) for the given parameters.
+ * @private
+ */
+function makeObjectName (uploaderUID, signingKey, uploadId, fileExt, bucket) {
+  const hash = getHash(uploaderUID, signingKey, uploadId, fileExt, bucket)
+  const nameWithHash = makeObjectNameGivenHash(
+    uploaderUID, uploadId, fileExt, hash)
+  return nameWithHash
+}
+
+/**
+ * Returns the full GCS object name using the specified hash string.
+ * @private
+ */
+function makeObjectNameGivenHash (uploaderUID, uploadId, fileExt, hash) {
+  assert(uploaderUID.indexOf('/') === -1)
+  return `${uploaderUID}/${uploadId}-${hash}.${fileExt}`
+}