@pbvision/partner-sdk 0.0.2 → 0.0.3

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
 
@@ -89,12 +108,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 +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
@@ -123,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:
@@ -154,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.2",
+  "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/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)