@pbvision/partner-sdk 0.1.4 → 0.1.5

package/README.md

@@ -10,7 +10,7 @@ standard length game, so we'll notify your servers when the results are ready.
 - [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 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)
@@ -108,7 +108,7 @@ import { PBVision } from '@pbvision/partner-sdk';
 const pbv = new PBVision(YOUR_API_KEY, { useProdServer: false });
 // you can omit this metadata, or provide some or all of this object—whatever you'd like!
 const optionalMetadata = {
-  userEmails: [],
+  userEmails: [], // passthrough partners must provide at least one email here
   name: 'Dink Championship 2024',
   desc: 'A longer description, if you want',
   gameStartEpoch: 1711393200, // when the game was played
@@ -136,6 +136,8 @@ data is enabled for your API key, only some of these fields may be present):
     "cutVideo": "https://storage.googleapis.com/pbv-pro/xyz/f50272db-69a8-49ed-9d92-3a4d067af87c/rallies.mp4",
     "insights": INSIGHTS_DATA,
     "stats": STATS_DATA,
+    "vid": STRING,
+    "aiEngineVersion": INT,
     "error": {
         "reason": "some explanation here..."
     }
@@ -152,6 +154,10 @@ data is enabled for your API key, only some of these fields may be present):
   - Explore the _stats_ schema at <https://pbv-public.github.io/stats?s=~stats~game>
   - Schema changes and diffs are in our [`pbv-public/stats` repo](https://github.com/pbv-public/stats/blob/dev/CHANGELOG.md)
 - `cutVideo` contains a link to the rally-sliced (dead time removed) .mp4.
+- 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].
 
 ## Video Guidelines
 

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

package/src/index.js

@@ -1,7 +1,6 @@
 import assert from 'node:assert'
 import fs from 'node:fs'
 
-import { makeSignedGoogleCloudStorageVideoObjectName } from './video-object-name.js'
 import fetch from 'node-fetch'
 
 const ENVIRONMENTS = {
@@ -26,10 +25,11 @@ const ENVIRONMENTS = {
 /** @public */
 export class PBVision {
   constructor (apiKey,  { useProdServer = false } = {}) {
-    assert(apiKey && apiKey.indexOf('_') !== -1,
-      `invalid API key: ${apiKey}`)
+    const underscoreIndex = apiKey.lastIndexOf('_')
+    assert(apiKey && underscoreIndex !== -1, `invalid API key: ${apiKey}`)
 
     this.apiKey = apiKey
+    this.uid = apiKey.substring(0, underscoreIndex)
     const config = useProdServer ? ENVIRONMENTS.prod : ENVIRONMENTS.test
     this.server = config.apiServer
     this.isDev = config === ENVIRONMENTS.test
@@ -47,20 +47,29 @@ export class PBVision {
     return this.__callAPI('webhook/set', { url: webhookUrl })
   }
 
+  /**
+   * @typedef {Object} VideoUrlToDownloadResponse
+   * @property {string} vid the ID of the new video
+   * @property {boolean} [hasCredits] for passthrough partners, this field will
+   *   be present and indicate whether the first user has any credits available
+   */
+
   /**
    * Tells PB Vision to download the specified video and process it. When
    * processing is complete, your webhook URL will receive a callback.
    *
    * @param {string} videoUrl the publicly available URL of the video
    * @param {VideoMetadata} [metadata]
+   * @returns {VideoUrlToDownloadResponse}
    */
   async sendVideoUrlToDownload (videoUrl, { userEmails = [], name, desc, gameStartEpoch } = {}) {
     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')
-    this.__callAPI(
+    const resp = await this.__callAPI(
       'add_video_by_url',
       { url: videoUrl, userEmails, name, desc, gameStartEpoch })
+    return JSON.parse(resp)
   }
 
   async __callAPI (path, body) {
@@ -95,34 +104,30 @@ export class PBVision {
 
   /**
    * 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.
+   *
    * @param {string} mp4Filename
    * @param {VideoMetadata} [metadata]
-   * @returns {string} the full Google Cloud Storage filename which this was
-   *   uploaded to
+   * @returns {VideoUrlToDownloadResponse}
    */
   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')
+    const pieces = mp4Filename.split('.')
+    const ext = pieces[pieces.length - 1]
+    const makeVIDResp = await this.__callAPI('make_video_id', { userEmails, name, desc, gameStartEpoch, fileExt: ext })
+    const { hasCredits, vid } = JSON.parse(makeVIDResp)
+    if (hasCredits === false) {
+      return { hasCredits }
     }
-
-    // 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)
-    }
-
+    const objName = `${this.uid}/${vid}.${ext}`
     await uploadToGCS(bucket, objName, mp4Filename)
-    return objName
+    const ret = { vid }
+    if (hasCredits !== undefined) {
+      ret.hasCredits = hasCredits
+    }
+    return ret
   }
 }
 

package/src/video-object-name.js

@@ -1,68 +0,0 @@
-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}`
-}