@eyepop.ai/eyepop 0.11.0 → 0.13.0

package/README.md

@@ -3,7 +3,7 @@ The EyePop.ai Node SDK provides convenient access to the EyePop.ai's inference A
 TypeScript or JavaScript language.
 ## Installation
 ```shell
-npm install --save eyepop
+npm install --save @eyepop.ai/eyepop
 ```
 ## Configuration
 The EyePop SDK needs to be configured with the __Pop Id__ and your __Authentication Credentials__. Credentials can 
@@ -11,7 +11,29 @@ be provided as:
 1. __Api Key__, server side only because this key must be kept secret
 2. __Session generated from Api Key__, server side generated session transported to client over trusted channel
 3. __Current Browser Session__, for developer running client code in the same browser session loghed into their EyePop Dashboard.
+### Configuration via Environment (Server Side)
+While you can provide a secret_key keyword argument, we recommend using dotenv to add EYEPOP_SECRET_KEY="My API Key" 
+to your .env file so that your API Key is not stored in source control. By default, the SDK will read the following environment variables:
+* `EYEPOP_POP_ID`: The Pop Id to use as an endpoint. You can copy and paste this string from your EyePop Dashboard in the Pop -> Settings section.
+* `EYEPOP_SECRET_KEY`: Your Secret Api Key. You can create Api Keys in the profile section of your EyePop dashboard.
+* `EYEPOP_URL`: (Optional) URL of the EyePop API service, if you want to use any other endpoint than production `http://api.eyepop.ai`  
 ### Authentication with Api Key
+Configuration and authorization with explicit defaults:
+```typescript
+import { EyePopSdk } from '@eyepop.ai/eyepop'
+(async() => {
+    const endpoint = EyePopSdk.endpoint({
+        // This is the default and can be omitted
+        popId: process.env['EYEPOP_POP_ID'],
+        // This is the default and can be omitted
+        auth : {secretKey: process.env['EYEPOP_SECRET_KEY']},
+    })
+    await endpoint.connect()
+    // do work ....
+    await endpoint.disconnect()
+})
+```
+Equivalent, but shorter:
 ```typescript
 import { EyePopSdk } from '@eyepop.ai/eyepop'
 (async() => {
@@ -38,7 +60,7 @@ server.listen(8080, '127.0.0.1');
 import { EyePopSdk } from '@eyepop.ai/eyepop'
 (async() => {
     const session = await (await fetch("http://127.0.0.1:8080")).json();
-    const endpoint = await EyePopSdk.endpoint({ session: session }).connect();
+    const endpoint = await EyePopSdk.endpoint({ auth: { session: session } }).connect();
     // do work ....
     await endpoint.disconnect();
 });
@@ -54,19 +76,24 @@ import { EyePopSdk } from '@eyepop.ai/eyepop'
 <body>
 <script>
     document.addEventListener("DOMContentLoaded", async (event) => {
-        let endpoint = await EyePopSdk.endpoint({ auth: { oAuth: true }, popId: '< Pop Id>' }).connect();
+        let endpoint = await EyePopSdk.endpoint({ auth: { oAuth2: true }, popId: '< Pop Id>' }).connect();
         // do work ....
         await endpoint.disconnect();
     });
 </script>
 </body>
 ```
-### Configuration via Environment (Server Side)
-While you can provide a secret_key keyword argument, we recommend using dotenv to add EYEPOP_SECRET_KEY="My API Key" 
-to your .env file so that your API Key is not stored in source control. By default, the SDK will read the following environment variables:
-* `EYEPOP_POP_ID`: The Pop Id to use as an endpoint. You can copy and paste this string from your EyePop Dashboard in the Pop -> Settings section.
-* `EYEPOP_SECRET_KEY`: Your Secret Api Key. You can create Api Keys in the profile section of your EyePop dashboard.
-* `EYEPOP_URL`: (Optional) URL of the EyePop API service, if you want to use any other endpoint than production `http://api.eyepop.ai`  
+To use an alternative environment, e.g. STAGING vs PRODUCTION, pass in the adjusted Auth0 configuration:
+```javascript
+// ...
+let endpoint = await EyePopSdk.endpoint({ 
+  auth: { oAuth2: {
+    audience: "https://dev-app.eyepop.ai",
+    domain: "dev-eyepop.us.auth0.com",
+    clientId: "jktx3YO2UnbkNPvr05PQWf26t1kNTJyg"
+  } }, popId: '< Pop Id>' }).connect();
+// ...
+```
 ## Usage Examples
 ### Uploading and processing one single image
 ```typescript
@@ -77,7 +104,7 @@ const example_image_path = 'examples/example.jpg';
 (async() => {
     const endpoint = await EyePopSdk.endpoint().connect()
     try {
-        let results = await endpoint.upload({filePath: example_image_path})
+        let results = await endpoint.process({path: example_image_path})
         for await (let result of results) {
             console.log(result)
         }        
@@ -89,15 +116,15 @@ const example_image_path = 'examples/example.jpg';
 1. `EyePopSdk.endpoint()` returns a local endpoint object, that will authenticate with the Api Key found in 
 EYEPOP_SECRET_KEY and load the worker configuration for the Pop identified by EYEPOP_POP_ID. 
 2. Call `endpoint.connect()` before any job is submitted and `endpoint.disconnect()` to release all resources.
-3. `endpoint.upload({filePath:'examples/example.jpg'})` initiates the upload to the local file to the worker service. 
+3. `endpoint.process({path:'examples/example.jpg'})` initiates the upload to the local file to the worker service. 
 The image will be queued and processed immediately when the worker becomes available.
-The result of endpoint.upload() implements `AsyncIterable<Prediction>` which can be iterated fir 'for await' as 
+The result of endpoint.upload() implements `AsyncIterable<Prediction>` which can be iterated with 'for await' as 
 shown in the example above. Predictions will become available when the submitted file becomes processed by the worker 
 and results are efficiently streamed back to the calling client. If the uploaded file is a video
 e.g. 'video/mp4' or image container format e.g. 'image/gif', the client will receive one prediction per image frame 
 until the entire file has been processed.
 
-4. Alternatively to `filePath` upload() also accepts a readable stream with a mandatory mime-type:
+4. Alternatively to `path` process() also accepts a readable stream with a mandatory mime-type:
 ```typescript
     // ... 
     let stream = fs.createReadStream(example_image_path)    
@@ -121,13 +148,12 @@ const example_image_path = 'examples/example.jpg';
     const canvas = createCanvas(image.width, image.height)
     const context = canvas.getContext("2d")
     context.drawImage(image, 0, 0)
-    const plot = EyePopSdk.plot(context)
 
     const endpoint = await EyePopSdk.endpoint().connect()
     try {
-        let results = await endpoint.upload({filePath: example_image_path})
+        let results = await endpoint.process({path: example_image_path})
         for await (let result of results) {
-            plot.prediction(result)
+            EyePopSdk.plot(context).prediction(result)
         }        
     } finally {
         await endpoint.disconnect()
@@ -144,7 +170,7 @@ const example_image_path = 'examples/example.jpg';
 })
 ```
 ### Asynchronous uploading and processing of images
-The above _synchronous_ way, upload() then iterate all results, is great for individual images or reasonable 
+The above _synchronous_ way, process() then iterate all results, is great for individual images or reasonable 
 sized batches. For larger batch sizes, or continuous stream of images, don't `await` the results but instead 
 use `then()` on the returned promise.
 ```typescript
@@ -156,12 +182,10 @@ const example_image_path = 'examples/example.jpg';
     const endpoint = await EyePopSdk.endpoint().connect()
     try {
         for (let i = 0; i < 100; i++) {
-            endpoint.upload({filePath: example_image_path}).then(async (results) => {
+            endpoint.process({path: example_image_path}).then(async (results) => {
                 for await (let result of results) {
                     console.log(`result for #${i}`, result)
                 }
-            }).catch((reason) => {
-                throw reason
             })
         }
     } finally {
@@ -184,7 +208,7 @@ const example_image_url = 'https://farm2.staticflickr.com/1080/1301049949_532835
 (async() => {
     const endpoint = await EyePopSdk.endpoint().connect()
     try {
-        let results = await endpoint.loadFrom(example_image_url)
+        let results = await endpoint.process({url: example_image_url})
         for await (let result of results) {
             console.log(result)
         }        
@@ -205,7 +229,7 @@ const example_video_url = 'https://demo-eyepop-videos.s3.amazonaws.com/test1_vlo
 (async() => {
     const endpoint = await EyePopSdk.endpoint().connect()
     try {
-        let results = await endpoint.loadFrom(example_image_url)
+        let results = await endpoint.process({url: example_image_url})
         for await (let result of results) {
             console.log(result)
         }        
@@ -225,7 +249,7 @@ const example_video_url = 'https://demo-eyepop-videos.s3.amazonaws.com/test1_vlo
 (async() => {
     const endpoint = EyePopSdk.endpoint().connect()
     try {
-        let results = await endpoint.loadFrom(example_image_url)
+        let results = await endpoint.process({url: example_image_url})
         for await (let result of results) {
             console.log(result)
             if (result['seconds'] >= 10.0) {