@eyepop.ai/eyepop 0.10.0 → 0.12.0

package/README.md

@@ -6,26 +6,84 @@ TypeScript or JavaScript language.
 npm install --save eyepop
 ```
 ## Configuration
-The EyePop SDK needs to be configured with the __Pop Id__ and your __Secret Api Key__. 
+The EyePop SDK needs to be configured with the __Pop Id__ and your __Authentication Credentials__. Credentials can 
+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(
+    const endpoint = EyePopSdk.endpoint({
         // This is the default and can be omitted
-        pop_id=process.env['EYEPOP_POP_ID'], 
+        popId: process.env['EYEPOP_POP_ID'],
         // This is the default and can be omitted
-        secret_key=process.env['EYEPOP_SECRET_KEY'],
-    )
+        auth : {secretKey: process.env['EYEPOP_SECRET_KEY']},
+    })
     await endpoint.connect()
     // do work ....
     await endpoint.disconnect()
 })
 ```
-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`  
+Equivalent, but shorter:
+```typescript
+import { EyePopSdk } from '@eyepop.ai/eyepop'
+(async() => {
+    const endpoint = EyePopSdk.endpoint()
+    await endpoint.connect()
+    // do work ....
+    await endpoint.disconnect()
+})
+```
+### Authentication with session generated from Api Key
+#### Server Side
+```javascript
+import { EyePopSdk } from '@eyepop.ai/eyepop'
+const getSession = async function (req, res) {
+    const endpoint = await EyePopSdk.endpoint().connect();
+    res.setHeader("Content-Type", "application/json");
+    res.writeHead(200);
+    res.end(JSON.stringify(await endpoint.session()));
+};
+const server = http.createServer(getSession);
+server.listen(8080, '127.0.0.1');
+```
+#### Client Side 
+```javascript
+import { EyePopSdk } from '@eyepop.ai/eyepop'
+(async() => {
+    const session = await (await fetch("http://127.0.0.1:8080")).json();
+    const endpoint = await EyePopSdk.endpoint({ auth: { session: session } }).connect();
+    // do work ....
+    await endpoint.disconnect();
+});
+```
+### Authentication with Current Browser Session
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <script src="https://cdn.jsdelivr.net/npm/@eyepop.ai/eyepop/dist/eyepop.min.js"></script>
+</head>
+<body>
+<script>
+    document.addEventListener("DOMContentLoaded", async (event) => {
+        let endpoint = await EyePopSdk.endpoint({ auth: { oAuth: true }, popId: '< Pop Id>' }).connect();
+        // do work ....
+        await endpoint.disconnect();
+    });
+</script>
+</body>
+```
 ## Usage Examples
 ### Uploading and processing one single image
 ```typescript
@@ -36,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)
         }        
@@ -48,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 
@@ -56,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)    
@@ -80,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()
@@ -103,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
@@ -115,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 {
@@ -143,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)
         }        
@@ -164,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)
         }        
@@ -184,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) {