@pbvision/partner-sdk 0.1.3 → 0.1.5

package/README.md

@@ -1,7 +1,7 @@
 # PB Vision Partner Documentation <!-- omit in toc -->
 
 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
+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.
 
 - [Installation](#installation)
@@ -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)
@@ -31,8 +31,8 @@ account. We'll send you an API Key.
 4. Initialize the SDK:
 
 ```javascript
-import { PBVision } from '@pbvision/partner-sdk'
-const pbv = new PBVision(YOUR_API_KEY)
+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
@@ -47,10 +47,10 @@ an HTTP POST request to a URL ("webhook") of your choice. You can use our SDK
 to tell our servers where you want us to notify your servers like this:
 
 ```javascript
-import { PBVision } from '@pbvision/partner-sdk'
+import { PBVision } from '@pbvision/partner-sdk';
 
-const pbv = new PBVision(YOUR_API_KEY)
-await pbv.setWebhook(YOUR_WEBHOOK_URL)
+const pbv = new PBVision(YOUR_API_KEY);
+await pbv.setWebhook(YOUR_WEBHOOK_URL);
 ```
 
 Alternatively, you can just use `curl`:
@@ -65,7 +65,7 @@ curl -X POST \
 
 ### Send Videos
 
-#### Option 1: PBV Downloads your video from a URL
+#### 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).
@@ -73,17 +73,17 @@ results, videos should follow our [guidelines](#video-guidelines).
 Next, tell us to download and work on the video. You can do this using our SDK:
 
 ```javascript
-import { PBVision } from '@pbvision/partner-sdk'
+import { PBVision } from '@pbvision/partner-sdk';
 
-const pbv = new PBVision(YOUR_API_KEY)
-// you can omit this metadata, or provide some or all of this object-- whatever you'd like!
+const pbv = new PBVision(YOUR_API_KEY);
+// you can omit this metadata, or provide some or all of this object—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.sendVideoUrlToDownload(YOUR_VIDEO_URL, optionalMetadata)
+  gameStartEpoch: 1711393200, // when the game was played
+};
+await pbv.sendVideoUrlToDownload(YOUR_VIDEO_URL, optionalMetadata);
 ```
 
 Alternatively, you can just use `curl`:
@@ -103,38 +103,41 @@ To use the production server instead of the test server, change `ko3kowqi6a` to
 You can directly upload your video from a file using the SDK too:
 
 ```javascript
-import { PBVision } from '@pbvision/partner-sdk'
+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 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
-}
-await pbv.uploadVideo(YOUR_VIDEO_FILENAME, optionalMetadata)
+  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).
+game (_if_ their email addresses were provided via `userEmails`).
 
 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).
 
-The HTTP POST body will contain JSON which looks like this:
+The HTTP POST body will contain JSON which looks like this (depending on which
+data is enabled for your API key, only some of these fields may be present):
 
 ```json
 {
     "from_url": "https://example.com/my-video.mp4",
-    "webpage": "https://app.pb.vision/video/xyz",
+    "webpage": "https://pb.vision/video/tvgz3pqij0ll",
     "cutVideo": "https://storage.googleapis.com/pbv-pro/xyz/f50272db-69a8-49ed-9d92-3a4d067af87c/rallies.mp4",
-    "events": EVENTS_DATA,
     "insights": INSIGHTS_DATA,
+    "stats": STATS_DATA,
+    "vid": STRING,
+    "aiEngineVersion": INT,
     "error": {
         "reason": "some explanation here..."
     }
@@ -144,30 +147,36 @@ The HTTP POST body will contain JSON which looks like this:
 - `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
-  - Explore the _events_ schema at <https://pbv-public.github.io/events/dev>
-  - Schema changes and diffs are in our [`pbv-public/events` repo](https://github.com/pbv-public/events/blob/dev/CHANGELOG.md)
-- `insights` - a summary of high-level stats about the video
-  - Explore the _insights_ schema at <https://pbv-public.github.io/insights/dev>
+- `insights` describes the pickleball game in a detailed, shot-by-shot format
+  - Explore the _insights_ schema at <https://pbv-public.github.io/insights?s=~insights~game>
   - Schema changes and diffs are in our [`pbv-public/insights` repo](https://github.com/pbv-public/insights/blob/dev/CHANGELOG.md)
+- `stats` various stats about the game for advanced players
+  - 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
 
 Requirements:
 
-- Video Encoding: **H.264** codec
-- Frame Rate: **30 or 60 FPS**
-- File Extension: `.mp4`
+- Comply with [PB Vision's framing guidelines](https://help.pb.vision/en/help/articles/1108176-video-recording-and-framing-tips)
+- Video Encoding: H.264 codec
+- Frame Rate: 30 or 60 FPS
+- Max Duration: 30 minutes
 
 For best results, we also recommend:
 
-- Follow our [**video framing** guidelines](https://www.pb.vision/video-tips)
+- File Extension: .mp4
 - Audio Encoding: MPEG-4 AAC
 - Resolution: 1080p
-- Max bitrate: 2 Mbps
-- Max file size: 1GB
-- Max duration: 30 minutes
+- Frame Rate: 30 FPS
+- Max Bitrate: 2 Mbps
+- Max File Size: 2GB
 
 ## Reference Guide
 
-- [JSDocs](https://pbv-public.github.io/partner-sdk-nodejs/)
+- [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.1.3",
+  "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.length === 31 && apiKey.indexOf('_') === 10,
-      `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}`
-}