@pbvision/partner-sdk 0.0.1 → 0.0.2

package/README.md

@@ -8,6 +8,8 @@ standard length game, so we'll notify your servers when the results are ready.
   - [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)
+    - [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)
   - [Step 4: Video Processing Done](#step-4-video-processing-done)
 - [SDK Setup](#sdk-setup)
 - [Video Guidelines](#video-guidelines)
@@ -44,6 +46,8 @@ curl -X POST \
 
 ### Step 3: 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 +57,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,6 +71,24 @@ curl -X POST \
      https://api-ko3kowqi6a-uc.a.run.app/partner/add_video_by_url
 ```
 
+#### 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)
+```
+
 ### Step 4: Video Processing Done
 
 When our AI is done processing your video, we will email the players in the

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.2",
   "license": "MIT",
   "type": "module",
   "engines": {

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,65 @@
+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
+ * @public
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+function makeObjectNameGivenHash (uploaderUID, uploadId, fileExt, hash) {
+  assert(uploaderUID.indexOf('/') === -1)
+  return `${uploaderUID}/${uploadId}-${hash}.${fileExt}`
+}