@pbvision/partner-sdk 0.0.2 → 0.1.0

package/README.md

@@ -4,24 +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 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)
-  - [Step 4: Video Processing Done](#step-4-video-processing-done)
-- [SDK Setup](#sdk-setup)
+- [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
@@ -44,7 +63,7 @@ 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
 
@@ -57,8 +76,14 @@ 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 userEmails = [] // optional!
-await pbv.sendVideoUrlToDownload(YOUR_VIDEO_URL, userEmails)
+// 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)
 ```
 
 Alternatively, you can just use `curl`:
@@ -79,7 +104,7 @@ 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)
-// you can omit this metadata, or provide it-- whatever you'd like!
+// you can omit this metadata, or provide some or all of this object-- whatever you'd like!
 const optionalMetadata = {
   userEmails: [],
   name: 'Dink Championship 2024',
@@ -89,12 +114,12 @@ const optionalMetadata = {
 await pbv.uploadVideo(YOUR_VIDEO_FILENAME, optionalMetadata)
 ```
 
-### Step 4: Video Processing Done
+## 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).
@@ -113,7 +138,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
@@ -123,21 +148,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:
@@ -154,3 +164,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.2",
+  "version": "0.1.0",
   "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

@@ -43,14 +43,15 @@ 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>} [userEmails] the email addresses of players in
-   *   this video; they'll be notified when the video is done processing
+   * @param {VideoMetadata} [metadata]
    */
-  async sendVideoUrlToDownload (videoUrl, userEmails = []) {
+  async sendVideoUrlToDownload (videoUrl, { userEmails = [], name, desc, gameStartEpoch } = {}) {
     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')
-    this.__callAPI('add_video_by_url', { url: videoUrl, userEmails })
+    assert(videoUrl.split('?')[0].endsWith('.mp4'), 'video URL must have the .mp4 extension')
+    this.__callAPI(
+      'add_video_by_url',
+      { url: videoUrl, userEmails, name, desc, gameStartEpoch })
   }
 
   async __callAPI (path, body) {

package/src/video-object-name.js

@@ -16,7 +16,7 @@ import crypto from 'node:crypto'
  * @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
+ * @protected
  */
 export function makeSignedGoogleCloudStorageVideoObjectName ({
   uploaderUID,
@@ -37,6 +37,7 @@ export function makeSignedGoogleCloudStorageVideoObjectName ({
  *
  * 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(
@@ -48,6 +49,7 @@ function getHash (uploaderUID, signingKey, uploadId, fileExt, bucket) {
 
 /**
  * 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)
@@ -58,6 +60,7 @@ function makeObjectName (uploaderUID, signingKey, uploadId, fileExt, bucket) {
 
 /**
  * Returns the full GCS object name using the specified hash string.
+ * @private
  */
 function makeObjectNameGivenHash (uploaderUID, uploadId, fileExt, hash) {
   assert(uploaderUID.indexOf('/') === -1)