@eyepop.ai/eyepop 3.14.7 → 3.15.0

package/README.md

@@ -1,168 +1,75 @@
 # EyePop.ai Node SDK
 
-The EyePop.ai Node SDK provides convenient access to the EyePop.ai's inference API from applications written in the
-TypeScript or JavaScript language.
+The EyePop.ai Node SDK provides JavaScript and TypeScript access to EyePop worker sessions for image and video inference.
 
 ## Installation
 
 ### Node
-EyePop Sdk is tested with the LTS versions `node v20.11.0` and `npm v10.2.4`. Getting started with:
-```shell
-npm install --save @eyepop.ai/eyepop
-```
-See the [Node example folder](https://github.com/eyepop-ai/eyepop-sdk-node/blob/main/examples/node) for code examples. 
 
-### Browser
-EyePop Sdk supports all model browsers and can be used with Javascript w/o any additional dependencies:  
-```html
-<script src="https://cdn.jsdelivr.net/npm/@eyepop.ai/eyepop/dist/eyepop.min.js"></script>
-```
-See the [Web example folder](https://github.com/eyepop-ai/eyepop-sdk-node/tree/main/examples/web/static) for code examples. 
+The SDK is tested with Node 20 LTS and newer.
 
-### React Native
 ```shell
 npm install --save @eyepop.ai/eyepop
 ```
 
-See the [ReactNative example folder](https://github.com/eyepop-ai/eyepop-sdk-node/tree/main/examples/react_native/upload-example) for code 
-examples and tips for to debug your configuration. 
-
-
-## Configuration
-
-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 api_key keyword argument, we recommend using dotenv to add EYEPOP_API_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_API_KEY`: Your 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`
+See the [Node examples](https://github.com/eyepop-ai/eyepop-sdk-node/blob/main/examples/node) for runnable scripts.
 
-### Authentication with Api Key
-
-Configuration and authorization with explicit defaults:
-
-```typescript
-import { EyePop } from '@eyepop.ai/eyepop'
-;async () => {
-    const endpoint = EyePop.workerEndpoint({
-        // This is the default and can be omitted
-        auth: { apiKey: process.env['EYEPOP_API_KEY'] },
-    })
-    await endpoint.connect()
-    // do work ....
-    await endpoint.disconnect()
-}
-```
+### Browser
 
-Equivalent, but shorter:
+Browser applications can use the bundled SDK directly:
 
-```typescript
-import { EyePop } from '@eyepop.ai/eyepop'
-;async () => {
-    const endpoint = await EyePop.workerEndpoint().connect()
-    // do work ....
-    await endpoint.disconnect()
-}
+```html
+<script src="https://cdn.jsdelivr.net/npm/@eyepop.ai/eyepop/dist/eyepop.min.js"></script>
 ```
 
-### Authentication with session generated from Api Key
+API keys must not be used in browser code. Browser apps should connect with sessions created by your trusted backend.
 
-#### Server Side
+### React Native
 
-```javascript
-import { EyePop } from '@eyepop.ai/eyepop'
+React Native applications should use the React Native package:
 
-const getSession = async function (req, res) {
-    const endpoint = await EyePop.workerEndpoint().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')
+```shell
+npm install --save @eyepop.ai/react-native-eyepop
 ```
 
-#### Client Side
+See the [React Native example](https://github.com/eyepop-ai/eyepop-sdk-node/tree/main/examples/react_native/upload-example).
 
-```javascript
-import { EyePop } from '@eyepop.ai/eyepop'
-;(async () => {
-    const session = await (await fetch('http://127.0.0.1:8080')).json()
-    const endpoint = await EyePop.workerEndpoint({ auth: { session: session } }).connect()
-    // do work ....
-    await endpoint.disconnect()
-})()
-```
+## Authentication
 
-### Authentication with Current Browser Session
+The SDK supports these authentication patterns:
 
-```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 EyePop.workerEndpoint({ auth: { oAuth2: true } }).connect()
-                await endpoint.changePop({ components: [{
-                    type: PopComponentType.INFERENCE,
-                    model: 'eyepop.person:latest',
-                    categoryName: 'person'
-                }]})
-                // do work ....
-                await endpoint.disconnect()
-            })
-        </script>
-    </body>
-</html>
-```
+- API key authentication for trusted server-side code.
+- Persistent worker session selection for provisioned deployments.
+- Browser OAuth for dashboard users building local demos.
 
-To use an alternative environment, e.g. STAGING vs PRODUCTION, pass in the adjusted Auth0 configuration:
+### Server-Side API Key
 
-```javascript
-// ...
-let endpoint = await EyePop.workerEndpoint({
-    auth: {
-        oAuth2: {
-            audience: 'https://dev-app.eyepop.ai',
-            domain: 'dev-eyepop.us.auth0.com',
-            clientId: 'jktx3YO2UnbkNPvr05PQWf26t1kNTJyg',
-        }
-    }
-}).connect()
-// ...
-```
+Set `EYEPOP_API_KEY` in your server environment. API keys are secrets and must not be exposed in browser bundles, mobile app bundles, or public repositories.
 
-## Usage Examples
+```shell
+export EYEPOP_API_KEY=<your_api_key>
+```
 
-### Uploading and processing one single image
+For provisioned persistent worker sessions, also set `EYEPOP_SESSION_UUID`.
 
 ```typescript
 import { EyePop } from '@eyepop.ai/eyepop'
 
-const example_image_path = 'examples/example.jpg'
-
 ;(async () => {
     const endpoint = await EyePop.workerEndpoint().connect()
     try {
-        await endpoint.changePop({ components: [{
-          type: PopComponentType.INFERENCE,
-          model: 'eyepop.person:latest',
-          categoryName: 'person'
-        }]})
-        let results = await endpoint.process({ source: { path: example_image_path } })
-        for await (let result of results) {
+        await endpoint.changePop({
+            components: [
+                {
+                    type: 'inference',
+                    model: 'eyepop.person:latest',
+                    categoryName: 'person',
+                },
+            ],
+        })
+
+        const results = await endpoint.process({ source: { path: 'examples/example.jpg' } })
+        for await (const result of results) {
             console.log(result)
         }
     } finally {
@@ -171,57 +78,35 @@ const example_image_path = 'examples/example.jpg'
 })()
 ```
 
-1. `EyePop.workerEndpoint()` returns a local endpoint object, that will authenticate with the Api Key found in
-   EYEPOP_API_KEY.
-2. Call `endpoint.connect()` before any job is submitted and `endpoint.disconnect()` to release all resources.
-3. Call `endpoint.changePop(...)` to define the Pop and its components to be executed by the endpoint, in this example
-   to use the ability `eyepop.person` to find all instances of persons in images and videos.
-4.`endpoint.process({ source: {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 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.
-
-5. Alternatively to `path` process() also accepts a readable stream with a mandatory mime-type:
+You can also pass the key explicitly from server-side configuration:
 
 ```typescript
-// ...
-let stream = fs.createReadStream(example_image_path)
-endpoint.upload({ source: { stream: readableStream, mimeType: 'image/jpeg' } })
-// ...
+const endpoint = await EyePop.workerEndpoint({
+    auth: { apiKey: process.env.EYEPOP_API_KEY },
+}).connect()
 ```
 
-Note: since v0.21.0 `EyePop.workerEndpoint()` was introduced and replaces `EyePop.endpoint()` which is now deprecated.
-Support for `EyePop.endpoint()` will be removed in v1.0.0.
-
-### Visualizing Results
-
-Visualization components are provided as separate modules. Please refer to the module's documentation for usage examples.
+### Persistent Sessions
 
--   [EyePop Render 2d](https://www.npmjs.com/package/@eyepop.ai/eyepop-render-2d)
+If EyePop has provisioned a persistent worker session for your deployment, set `EYEPOP_SESSION_UUID` in the trusted server environment or pass `sessionUuid` explicitly.
 
-### Asynchronous uploading and processing of images
-
-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.
+```shell
+export EYEPOP_API_KEY=<your_api_key>
+export EYEPOP_SESSION_UUID=<your_session_uuid>
+```
 
 ```typescript
 import { EyePop } from '@eyepop.ai/eyepop'
 
-const example_image_path = 'examples/example.jpg'
-
 ;(async () => {
-    const endpoint = await EyePop.workerEndpoint().connect()
+    const endpoint = await EyePop.workerEndpoint({
+        sessionUuid: process.env.EYEPOP_SESSION_UUID,
+    }).connect()
+
     try {
-        for (let i = 0; i < 100; i++) {
-            endpoint.process({ source: { path: example_image_path } }).then(async results => {
-                for await (let result of results) {
-                    console.log(`result for #${i}`, result)
-                }
-            })
+        const results = await endpoint.process({ source: { path: 'sample.mp4' } })
+        for await (const result of results) {
+            console.log(result)
         }
     } finally {
         await endpoint.disconnect()
@@ -229,102 +114,114 @@ const example_image_path = 'examples/example.jpg'
 })()
 ```
 
-This will result in a most efficient processing, i.e. uploads will be processed in parallel (up to five HTTP
-connections per endpoint) and results will be processed by your code as soon as they are available.
-
-### Loading images from URLs
+Persistent sessions are normally preconfigured. In that case, process media directly and do not call `changePop()` unless your deployment is meant to accept runtime Pop changes.
 
-Alternatively to uploading files, you can also submit a publicly accessible URL for processing. Supported protocols are:
+### Browser and Mobile Clients
 
--   HTTP(s) URLs with response Content-Type image/_ or video/_
--   RTSP (live-streaming)
--   RTMP (live-streaming)
+Do not put `EYEPOP_API_KEY` in browser or mobile application code. Create EyePop sessions from a trusted backend, then pass only the session JSON to the client.
 
-```typescript
-import { EyePop } from '@eyepop.ai/eyepop'
+### Browser OAuth for Local Dashboard Demos
 
-const example_image_url = 'https://farm2.staticflickr.com/1080/1301049949_532835a8b5_z.jpg'
+Dashboard users can run local browser demos with the current browser session:
 
-;(async () => {
-    const endpoint = await EyePop.workerEndpoint().connect()
-    try {
-        let results = await endpoint.process({ source: { url: example_image_url } })
-        for await (let result of results) {
-            console.log(result)
+```html
+<script>
+    document.addEventListener('DOMContentLoaded', async () => {
+        const endpoint = await EyePop.workerEndpoint({ auth: { oAuth2: true } }).connect()
+        try {
+            await endpoint.changePop({
+                components: [
+                    {
+                        type: 'inference',
+                        model: 'eyepop.person:latest',
+                        categoryName: 'person',
+                    },
+                ],
+            })
+        } finally {
+            await endpoint.disconnect()
         }
-    } finally {
-        await endpoint.disconnect()
-    }
-})()
+    })
+</script>
 ```
 
-### Processing Videos
+## Processing Media
 
-You can process videos via upload or public URLs. This example shows how to process all video frames of a file
-retrieved from a public URL.
+### Local Files
 
 ```typescript
-import { EyePop } from '@eyepop.ai/eyepop'
+const results = await endpoint.process({ source: { path: 'examples/example.jpg' } })
+for await (const result of results) {
+    console.log(result)
+}
+```
 
-const example_video_url = 'https://demo-eyepop-videos.s3.amazonaws.com/test1_vlog.mp4'
+`process()` returns an `AsyncIterable` of predictions. Images normally produce one prediction. Videos and animated image containers produce one prediction per frame.
 
-;(async () => {
-    const endpoint = await EyePop.workerEndpoint().connect()
-    try {
-        let results = await endpoint.process({ source: { url: example_video_url } })
-        for await (let result of results) {
-            console.log(result)
-        }
-    } finally {
-        await endpoint.disconnect()
-    }
-})()
+### Readable Streams
+
+Streams require an explicit MIME type:
+
+```typescript
+import fs from 'node:fs'
+
+const stream = fs.createReadStream('examples/example.jpg')
+const results = await endpoint.process({
+    source: { stream, mimeType: 'image/jpeg' },
+})
 ```
 
-### Canceling Jobs
+### Public URLs
 
-Any job that has been queued or is in-progress can be cancelled. E.g. stop the video processing after
-predictions have been processed for 10 seconds duration of the video.
+Public HTTP(S), RTSP, and RTMP URLs can be processed without uploading the file from your application.
 
 ```typescript
-import { EyePop } from '@eyepop.ai/eyepop'
+const results = await endpoint.process({
+    source: { url: 'https://demo-eyepop-videos.s3.amazonaws.com/test1_vlog.mp4' },
+})
+```
 
-const example_video_url = 'https://demo-eyepop-videos.s3.amazonaws.com/test1_vlog.mp4'
+### Canceling Jobs
 
-;(async () => {
-    const endpoint = EyePop.workerEndpoint().connect()
-    try {
-        let results = await endpoint.process({ source: { url: example_video_url } })
-        for await (let result of results) {
-            console.log(result)
-            if (result['seconds'] >= 10.0) {
-                results.cancel()
-            }
-        }
-    } finally {
-        await endpoint.disconnect()
+Queued and in-progress jobs can be cancelled from the result iterator:
+
+```typescript
+const results = await endpoint.process({
+    source: { url: 'https://demo-eyepop-videos.s3.amazonaws.com/test1_vlog.mp4' },
+})
+
+for await (const result of results) {
+    console.log(result)
+    if ((result.seconds ?? 0) >= 10) {
+        results.cancel()
     }
-})()
+}
 ```
 
-## Other Usage Options
+## Endpoint Options
 
-#### Auto start workers
+By default, `EyePop.workerEndpoint().connect()` starts a worker when needed and cancels queued jobs on that worker when it connects.
 
-By default, `EyePop.workerEndpoint().connect()` will start a worker if none is running yet. To disable this behavior
-create an endpoint with `EyePop.endpoint({autoStart: false})`.
+Disable worker startup:
+
+```typescript
+const endpoint = await EyePop.workerEndpoint({ autoStart: false }).connect()
+```
+
+Keep pending jobs:
+
+```typescript
+const endpoint = await EyePop.workerEndpoint({ stopJobs: false }).connect()
+```
 
-#### Stop pending jobs
+## Visualization
 
-By default, `EyePop.workerEndpoint().connect()` will cancel all currently running or queued jobs on the worker.
-It is assumed that the caller _takes full control_ of that worker. To disable this behavior create an endpoint with
-`EyePop.endpoint({stopJobs: false})`.
+Rendering helpers are provided by [@eyepop.ai/eyepop-render-2d](https://www.npmjs.com/package/@eyepop.ai/eyepop-render-2d).
 
-## Data endpoint (PREVIEW)
+## Data Endpoint Preview
 
-To support managing your own datasets and control model optimization v0.21.0 introduces `EyePop.dataEndpoint()`,
-an experimental pre-release which is subject to change. An officially supported version will be released with v2.0.0
+`EyePop.dataEndpoint()` provides preview support for dataset management and model optimization workflows. This API is experimental and subject to change.
 
-## Composable Pops (PREVIEW)
+## Composable Pops Preview
 
-See [Composable Pops](composable-pops.md) for a preview of client side composability of pops, introduced in v1.0.0.
+See [Composable Pops](composable-pops.md) for a preview of client-side Pop composition.

package/dist/eyepop.index.d.mts

@@ -941,11 +941,6 @@ interface PlatformSupport {
 }
 interface Options {
     auth?: Authentication | undefined;
-    /**
-     * Override the default base URL for the API, e.g., "https://api.eyepop.ai/"
-     *
-     * Defaults to process.env['EYEPOP_URL'].
-     */
     eyepopUrl?: string | undefined;
     jobQueueLength?: number;
     logger?: Logger | undefined;
@@ -1063,9 +1058,10 @@ declare enum TransientPopId {
 }
 interface WorkerOptions extends Options {
     /**
-     * TODO: deprecated, defaults to process.env['EYEPOP_POP_ID'].
+     * TODO: deprecated, support for pop id will be removed in 3.16
      */
     popId?: string | TransientPopId | undefined;
+    sessionUuid?: string | undefined;
     autoStart?: boolean;
     stopJobs?: boolean;
     isLocalMode?: boolean;
@@ -1130,7 +1126,9 @@ declare class WorkerEndpoint extends Endpoint<WorkerEndpoint> {
     private static SESSION_DEAD;
     private static WAIT_FOR_IS_READY;
     private static CHECK_FOR_IS_READY_INTERVAL;
-    private startComputeSession;
+    private getComputeSession;
+    private getOnDemandComputeSession;
+    private getPermanentComputeSession;
     private startTransientPipeline;
 }
 

package/dist/eyepop.index.d.ts

@@ -941,11 +941,6 @@ interface PlatformSupport {
 }
 interface Options {
     auth?: Authentication | undefined;
-    /**
-     * Override the default base URL for the API, e.g., "https://api.eyepop.ai/"
-     *
-     * Defaults to process.env['EYEPOP_URL'].
-     */
     eyepopUrl?: string | undefined;
     jobQueueLength?: number;
     logger?: Logger | undefined;
@@ -1063,9 +1058,10 @@ declare enum TransientPopId {
 }
 interface WorkerOptions extends Options {
     /**
-     * TODO: deprecated, defaults to process.env['EYEPOP_POP_ID'].
+     * TODO: deprecated, support for pop id will be removed in 3.16
      */
     popId?: string | TransientPopId | undefined;
+    sessionUuid?: string | undefined;
     autoStart?: boolean;
     stopJobs?: boolean;
     isLocalMode?: boolean;
@@ -1130,7 +1126,9 @@ declare class WorkerEndpoint extends Endpoint<WorkerEndpoint> {
     private static SESSION_DEAD;
     private static WAIT_FOR_IS_READY;
     private static CHECK_FOR_IS_READY_INTERVAL;
-    private startComputeSession;
+    private getComputeSession;
+    private getOnDemandComputeSession;
+    private getPermanentComputeSession;
     private startTransientPipeline;
 }