camstreamerlib 4.0.0-beta.162 → 4.0.0-beta.164

package/README.md

@@ -1,13 +1,8 @@
 # CamStreamerLib - BETA
 
-**This is beta version of CamStreamerLib v4, dont use it on production. Is going to be changed significantly.**
+Web and Node.js helper library for CamStreamer ACAP applications.
 
-**The documentation is in progress**
-
-Node.js helper library for CamStreamer ACAP applications.
-
-The library is primarily developed for the CamScripter ACAP application running directly in Axis cameras.
-Examples of CamScripter packages can be found at https://github.com/CamStreamer/CamScripterApp_examples
+The library is primarily developed for ACAP applications running directly in Axis cameras.
 
 ## Installation
 
@@ -26,7 +21,7 @@ npm install camstreamerlib
 | [CamSwitcherAPI](doc/CamSwitcherAPI.md)            | Module to access CamSwitcher API.                                                                                      |
 | [PlaneTrackerAPI](doc/PlaneTrackerAPI.md)          | Module to access PlaneTracker API.                                                                                     |
 | [CamStreamerEvents](doc/ws/CamStreamerEvents.md)   | Module which allows receiving events from CamStreamer ACAP application.                                                |
-| [OverlayEvents](doc/ws/OverlayEvents.md)           | Module which allows receiving events from Overlay ACAP application.                                                    |
+| [CamOverlayEvents](doc/ws/CamOverlayEvents.md)     | Module which allows receiving events from CamOverlay ACAP application.                                                 |
 | [CamSwitcherEvents](doc/ws/CamSwitcherEvents.md)   | Module which allows receiving events from CamSwitcher ACAP application.                                                |
 | [PlaneTrackerEvents](doc/ws/PlaneTrackerEvents.md) | Module which allows receiving events from PlaneTracker ACAP application.                                               |
 
@@ -56,11 +51,11 @@ npm install camstreamerlib
 
 ### ACAP API Class Constructors Updated
 
-All ACAP API classes now **require a client instance to be passed into their constructors** instead of options object.
+All ACAP API classes now **require a client instance to be passed into their constructors** instead of `options` object.
 
 -   This change improves flexibility by allowing you to use either the Node or Web client, depending on your environment.
 
-Example (before → now):
+**Example (before → now)**:
 
 ```typescript
 // Before
@@ -78,6 +73,12 @@ const coApi = new CamOverlayAPI({
 import { DefaultClient } from 'camstreamerlib/web';
 import { CamOverlayAPI } from 'camstreamerlib';
 
+// Use DefaultClient in constructor
+const coApi = new CamOverlayAPI(
+    new DefaultClient()
+);
+
+// Or adjust DefaultClient default values with your own
 const coApi = new CamOverlayAPI(
     new DefaultClient({
         tls: false,
@@ -109,17 +110,43 @@ import { Painter } from 'camstreamerlib/node';
 import { DefaultClient } from 'camstreamerlib/web';
 ```
 
-> Note: To ensure compatibility, set the module resolution in your projects tsconfig.json to `"moduleResolution": "bundler"`.
+> :information_source: Note: To ensure compatibility, set the module resolution in your web projects tsconfig.json to `"moduleResolution": "bundler"`.
 
-### Class and Method Refactored
+### Classes and Methods Refactored
 
 -   **CameraVapix API** has been renamed to [**VapixAPI**](doc/VapixAPI.md).
 -   **DefaultAgent** has been refactored into two separate classes - one for node, one for web as [**DefaultClient**](doc/Client.md)
 -   Several method names and parameter names across the library have been updated for consistency and clarity.
+-   New API modules and endpoints have been introduced, providing extended functionality and better coverage of the underlying service.
 
-> Please refer to [the documentation](#documentation-for-acap-and-camera-api).
+### Stream List Migration
 
--   New API modules and endpoints have been introduced, providing extended functionality and better coverage of the underlying service.
+-   `CamStreamerAPI.getStreamList()` and `getStream()` now throw a **`MigrationError`** when old-format (v3) stream data is detected on the camera.
+-   `MigrationError` provides four arrays to help you handle the transition: `.valid`, `.old`, `.invalid`, and `.unknown`.
+
+```typescript
+import { MigrationError } from 'camstreamerlib';
+
+try {
+    const streams = await csApi.getStreamList();
+} catch (e) {
+    if (e instanceof MigrationError) {
+        console.log('Valid streams:', e.valid);
+        console.log('Old-format streams needing migration:', e.old);
+    }
+}
+```
+
+### CreatePackage Script Path Changed
+
+-   The path to the `CreatePackage` script changed from `camstreamerlib/CreatePackage.js` to `camstreamerlib/bin/CreatePackage.js`.
+-   Update any `package.json` scripts accordingly:
+
+```json
+"scripts": {
+    "create-package": "node node_modules/camstreamerlib/bin/CreatePackage.js"
+}
+```
 
 <hr/>
 </details>
@@ -204,3 +231,5 @@ The zip package is created in the current directory. You can choose different lo
     "create-package": "node node_modules/camstreamerlib/bin/CreatePackage.js -i -e=react"
 }
 ```
+
+> :warning: Path to `CreatePackage` script has changed from `camstreamerlib/CreatePackage.js` to `camstreamerlib/bin/CreatePackage.js` (from v.4.0.0)

package/cjs/CamStreamerAPI.d.ts

@@ -31,6 +31,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -120,6 +121,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -214,6 +216,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -311,6 +314,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -397,6 +401,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -483,6 +488,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -569,6 +575,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -655,6 +662,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -741,6 +749,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -827,6 +836,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -913,6 +923,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -999,6 +1010,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -1085,6 +1097,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -1171,6 +1184,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -1257,6 +1271,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -1343,6 +1358,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -1429,6 +1445,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -1515,6 +1532,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -1601,6 +1619,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -1687,6 +1706,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -1784,6 +1804,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -1873,6 +1894,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -1967,6 +1989,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -2064,6 +2087,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -2150,6 +2174,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -2236,6 +2261,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -2322,6 +2348,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -2408,6 +2435,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -2494,6 +2522,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -2580,6 +2609,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -2666,6 +2696,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -2752,6 +2783,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -2838,6 +2870,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -2924,6 +2957,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -3010,6 +3044,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -3096,6 +3131,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -3182,6 +3218,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -3268,6 +3305,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -3354,6 +3392,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;
@@ -3440,6 +3479,7 @@ export declare class CamStreamerAPI<Client extends IClient<TResponse, any>> exte
         enabled: boolean;
         active: boolean;
         title: string;
+        callApi: boolean;
         trigger: {
             type: "manual";
             port?: number | undefined;

package/cjs/VapixAPI.d.ts

@@ -17,15 +17,6 @@ export declare class VapixAPI<Client extends IClient<TResponse, any>> extends Ba
         bitRates: number[];
     }[]>;
     performAutofocus(options?: THttpRequestOptions): Promise<void>;
-    checkSDCard(options?: THttpRequestOptions): Promise<{
-        status: "OK" | "connected" | "disconnected";
-        totalSize: number;
-        freeSize: number;
-    }>;
-    mountSDCard(options?: THttpRequestOptions): Promise<number>;
-    unmountSDCard(options?: THttpRequestOptions): Promise<number>;
-    private _doSDCardMountAction;
-    fetchSDCardJobProgress(jobId: number, options?: THttpRequestOptions): Promise<number>;
     downloadCameraReport(options?: THttpRequestOptions): Promise<string>;
     getSystemLog(options?: THttpRequestOptions): Promise<string>;
     getMaxFps(channel: number, options?: THttpRequestOptions): Promise<number>;
@@ -43,6 +34,15 @@ export declare class VapixAPI<Client extends IClient<TResponse, any>> extends Ba
     fetchRemoteDeviceInfo<T extends Record<string, any>>(payload: T, options?: THttpRequestOptions): Promise<any>;
     getHeaders(options?: THttpRequestOptions): Promise<Record<string, string>>;
     setHeaders(headers: Record<string, string>, options?: THttpRequestOptions): Promise<void>;
+    checkSDCard(options?: THttpRequestOptions): Promise<{
+        status: "OK" | "connected" | "disconnected";
+        totalSize: number;
+        freeSize: number;
+    }>;
+    mountSDCard(options?: THttpRequestOptions): Promise<number>;
+    unmountSDCard(options?: THttpRequestOptions): Promise<number>;
+    private _doSDCardMountAction;
+    fetchSDCardJobProgress(jobId: number, options?: THttpRequestOptions): Promise<number>;
     getParameter(paramNames: string | string[], options?: THttpRequestOptions): Promise<Record<string, string>>;
     setParameter(params: Record<string, string | number | boolean>, options?: THttpRequestOptions): Promise<void>;
     getGuardTourList(options?: THttpRequestOptions): Promise<{

package/cjs/VapixAPI.js

@@ -98,65 +98,6 @@ class VapixAPI extends BasicAPI_1.BasicAPI {
             }, options);
         }
     }
-    async checkSDCard(options) {
-        const res = await this._postUrlEncoded('/axis-cgi/disks/list.cgi', {
-            diskid: 'SD_DISK',
-        }, options);
-        const xmlText = await res.text();
-        const parser = new fast_xml_parser_1.XMLParser({
-            ignoreAttributes: false,
-            attributeNamePrefix: '',
-            allowBooleanAttributes: true,
-        });
-        const result = parser.parse(xmlText);
-        const data = result.root.disks.disk;
-        return VapixAPI_1.sdCardInfoSchema.parse({
-            totalSize: parseInt(data.totalsize),
-            freeSize: parseInt(data.freesize),
-            status: VapixAPI_1.sdCardWatchedStatuses.includes(data.status) ? data.status : 'disconnected',
-        });
-    }
-    mountSDCard(options) {
-        return this._doSDCardMountAction('MOUNT', options);
-    }
-    unmountSDCard(options) {
-        return this._doSDCardMountAction('UNMOUNT', options);
-    }
-    async _doSDCardMountAction(action, options) {
-        const res = await this._postUrlEncoded('/axis-cgi/disks/mount.cgi', {
-            action: action,
-            diskid: 'SD_DISK',
-        }, options);
-        const textXml = await res.text();
-        const parser = new fast_xml_parser_1.XMLParser({
-            ignoreAttributes: false,
-            attributeNamePrefix: '',
-            allowBooleanAttributes: true,
-        });
-        const result = parser.parse(textXml);
-        const job = result.root.job;
-        if (job.result !== 'OK') {
-            throw new errors_1.SDCardActionError(action, job.description);
-        }
-        return Number(job.jobid);
-    }
-    async fetchSDCardJobProgress(jobId, options) {
-        const res = await this._postUrlEncoded('/axis-cgi/disks/job.cgi', {
-            jobid: String(jobId),
-            diskid: 'SD_DISK',
-        }, options);
-        const textXml = await res.text();
-        const parser = new fast_xml_parser_1.XMLParser({
-            ignoreAttributes: false,
-            attributeNamePrefix: '',
-            allowBooleanAttributes: true,
-        });
-        const job = parser.parse(textXml).root.job;
-        if (job.result !== 'OK') {
-            throw new errors_1.SDCardJobError(job.description);
-        }
-        return Number(job.progress);
-    }
     downloadCameraReport(options) {
         return this._getText('/axis-cgi/serverreport.cgi', { mode: 'text' }, options);
     }
@@ -242,6 +183,65 @@ class VapixAPI extends BasicAPI_1.BasicAPI {
         const data = { apiVersion: '1.0', method: 'set', params: headers };
         await this._postJsonEncoded('/axis-cgi/customhttpheader.cgi', data, undefined, options);
     }
+    async checkSDCard(options) {
+        const res = await this._postUrlEncoded('/axis-cgi/disks/list.cgi', {
+            diskid: 'SD_DISK',
+        }, options);
+        const xmlText = await res.text();
+        const parser = new fast_xml_parser_1.XMLParser({
+            ignoreAttributes: false,
+            attributeNamePrefix: '',
+            allowBooleanAttributes: true,
+        });
+        const result = parser.parse(xmlText);
+        const data = result.root.disks.disk;
+        return VapixAPI_1.sdCardInfoSchema.parse({
+            totalSize: parseInt(data.totalsize),
+            freeSize: parseInt(data.freesize),
+            status: VapixAPI_1.sdCardWatchedStatuses.includes(data.status) ? data.status : 'disconnected',
+        });
+    }
+    mountSDCard(options) {
+        return this._doSDCardMountAction('MOUNT', options);
+    }
+    unmountSDCard(options) {
+        return this._doSDCardMountAction('UNMOUNT', options);
+    }
+    async _doSDCardMountAction(action, options) {
+        const res = await this._postUrlEncoded('/axis-cgi/disks/mount.cgi', {
+            action: action,
+            diskid: 'SD_DISK',
+        }, options);
+        const textXml = await res.text();
+        const parser = new fast_xml_parser_1.XMLParser({
+            ignoreAttributes: false,
+            attributeNamePrefix: '',
+            allowBooleanAttributes: true,
+        });
+        const result = parser.parse(textXml);
+        const job = result.root.job;
+        if (job.result !== 'OK') {
+            throw new errors_1.SDCardActionError(action, job.description);
+        }
+        return Number(job.jobid);
+    }
+    async fetchSDCardJobProgress(jobId, options) {
+        const res = await this._postUrlEncoded('/disks/job.cgi', {
+            jobid: String(jobId),
+            diskid: 'SD_DISK',
+        }, options);
+        const textXml = await res.text();
+        const parser = new fast_xml_parser_1.XMLParser({
+            ignoreAttributes: false,
+            attributeNamePrefix: '',
+            allowBooleanAttributes: true,
+        });
+        const job = parser.parse(textXml).root.job;
+        if (job.result !== 'OK') {
+            throw new errors_1.SDCardJobError(job.description);
+        }
+        return Number(job.progress);
+    }
     async getParameter(paramNames, options) {
         const response = await this._postUrlEncoded('/axis-cgi/param.cgi', {
             action: 'list',