@eyepop.ai/eyepop 0.11.0 → 0.12.0

package/README.md

@@ -11,11 +11,34 @@ 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 = await EyePopSdk.endpoint().connect()
+    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() => {
+    const endpoint = EyePopSdk.endpoint()
+    await endpoint.connect()
     // do work ....
     await endpoint.disconnect()
 })
@@ -38,7 +61,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();
 });
@@ -61,12 +84,6 @@ import { EyePopSdk } from '@eyepop.ai/eyepop'
 </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`  
 ## Usage Examples
 ### Uploading and processing one single image
 ```typescript
@@ -77,7 +94,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,7 +106,7 @@ 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 
 shown in the example above. Predictions will become available when the submitted file becomes processed by the worker 
@@ -97,7 +114,7 @@ and results are efficiently streamed back to the calling client. If the uploaded
 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 +138,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 +160,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 +172,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 +198,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 +219,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 +239,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) {