een-api-toolkit 0.1.4 → 0.1.7

package/dist/index.d.ts

@@ -442,7 +442,7 @@ export declare interface EenToolkitConfig {
  *
  * @category Types
  */
-export declare type ErrorCode = 'AUTH_REQUIRED' | 'AUTH_FAILED' | 'TOKEN_EXPIRED' | 'API_ERROR' | 'NETWORK_ERROR' | 'VALIDATION_ERROR' | 'NOT_FOUND' | 'FORBIDDEN' | 'RATE_LIMITED' | 'UNKNOWN_ERROR';
+export declare type ErrorCode = 'AUTH_REQUIRED' | 'AUTH_FAILED' | 'TOKEN_EXPIRED' | 'API_ERROR' | 'NETWORK_ERROR' | 'VALIDATION_ERROR' | 'NOT_FOUND' | 'FORBIDDEN' | 'RATE_LIMITED' | 'SERVICE_UNAVAILABLE' | 'UNKNOWN_ERROR';
 
 /* Excluded from this release type: failure */
 
@@ -724,11 +724,200 @@ export declare function getConfig(): EenToolkitConfig;
  */
 export declare function getCurrentUser(): Promise<Result<UserProfile>>;
 
+/**
+ * Get a live image from a camera.
+ *
+ * @remarks
+ * Fetches a new live image from the specified camera. This call waits until
+ * a new image is available from the device. The image is returned as a
+ * base64 data URL that can be used directly in an HTML img element.
+ *
+ * Note: Live images only support the 'preview' stream type.
+ *
+ * **Memory Considerations**: Images are loaded into memory and base64 encoded,
+ * adding ~33% size overhead. Typical preview images are <500KB. For high-frequency
+ * polling, consider implementing error backoff and limiting concurrent requests.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/getliveimage).
+ *
+ * @param params - Parameters including the required deviceId
+ * @returns A Result containing the live image data or an error
+ *
+ * @example
+ * ```typescript
+ * import { getLiveImage } from 'een-api-toolkit'
+ *
+ * const { data, error } = await getLiveImage({ deviceId: 'camera-123' })
+ *
+ * if (data) {
+ *   // Display in an img element
+ *   document.getElementById('cameraImage').src = data.imageData
+ *   console.log('Image timestamp:', data.timestamp)
+ * }
+ *
+ * // Continuously update the image with proper error handling
+ * let isRunning = true
+ * async function refreshLoop() {
+ *   const imgElement = document.getElementById('cameraImage') as HTMLImageElement
+ *   while (isRunning) {
+ *     const { data, error } = await getLiveImage({ deviceId: 'camera-123' })
+ *     if (error) {
+ *       console.error('Refresh failed:', error.message)
+ *       break // Stop on error
+ *     }
+ *     if (data) {
+ *       imgElement.src = data.imageData
+ *     }
+ *     await new Promise(r => setTimeout(r, 1000))
+ *   }
+ * }
+ * // Call refreshLoop() to start, set isRunning = false to stop
+ * ```
+ *
+ * @category Media
+ */
+export declare function getLiveImage(params: GetLiveImageParams): Promise<Result<LiveImageResult>>;
+
+/**
+ * Parameters for getting a live image.
+ *
+ * @remarks
+ * Used to fetch a live image from a camera.
+ * Note: Live images only support 'preview' type.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/getliveimage).
+ *
+ * @example
+ * ```typescript
+ * import { getLiveImage } from 'een-api-toolkit'
+ *
+ * const { data } = await getLiveImage({
+ *   deviceId: 'camera-123',
+ *   type: 'preview'
+ * })
+ *
+ * if (data) {
+ *   // Display the image in an <img> element
+ *   imgElement.src = data.imageData
+ * }
+ * ```
+ *
+ * @category Media
+ */
+export declare interface GetLiveImageParams {
+    /** The ID of the device (camera) - required */
+    deviceId: string;
+    /** Stream type - only 'preview' is supported for live images */
+    type?: 'preview';
+}
+
 /**
  * Get the proxy URL
  */
 export declare function getProxyUrl(): string | undefined;
 
+/**
+ * Get a recorded image from a camera.
+ *
+ * @remarks
+ * Fetches a recorded image from the specified camera at a specific timestamp.
+ * You can specify the desired timestamp using various operators (exact, gte, lte, etc.)
+ * or use a pageToken from a previous request to navigate through images.
+ *
+ * The image is returned as a base64 data URL that can be used directly in an HTML img element.
+ *
+ * Note: The 'main' type is rate-limited and requires an actual recording at the timestamp.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/getrecordedimage).
+ *
+ * @param params - Parameters including deviceId/pageToken and timestamp options
+ * @returns A Result containing the recorded image data or an error
+ *
+ * @example
+ * ```typescript
+ * import { getRecordedImage } from 'een-api-toolkit'
+ *
+ * // Get image at or after a specific time
+ * const { data, error } = await getRecordedImage({
+ *   deviceId: 'camera-123',
+ *   type: 'preview',
+ *   timestamp__gte: '2024-01-15T10:00:00.000Z'
+ * })
+ *
+ * if (data) {
+ *   imgElement.src = data.imageData
+ *   console.log('Actual timestamp:', data.timestamp)
+ *
+ *   // Get the next image using the token
+ *   if (data.nextToken) {
+ *     const { data: nextImage } = await getRecordedImage({
+ *       pageToken: data.nextToken
+ *     })
+ *   }
+ * }
+ * ```
+ *
+ * @category Media
+ */
+export declare function getRecordedImage(params: GetRecordedImageParams): Promise<Result<RecordedImageResult>>;
+
+/**
+ * Parameters for getting a recorded image.
+ *
+ * @remarks
+ * Used to fetch a recorded image from a camera at a specific timestamp.
+ * Either deviceId with a timestamp parameter, or pageToken is required.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/getrecordedimage).
+ *
+ * @example
+ * ```typescript
+ * import { getRecordedImage } from 'een-api-toolkit'
+ *
+ * // Get image at or after a specific time
+ * const { data } = await getRecordedImage({
+ *   deviceId: 'camera-123',
+ *   type: 'preview',
+ *   timestamp__gte: '2024-01-15T10:00:00.000Z'
+ * })
+ * ```
+ *
+ * @category Media
+ */
+export declare interface GetRecordedImageParams {
+    /** The ID of the device (camera) - required unless using pageToken */
+    deviceId?: string;
+    /** Token from previous request to fetch next/previous image */
+    pageToken?: string;
+    /** Stream type (preview or main) */
+    type?: MediaStreamType;
+    /** Return first image with timestamp less than this value */
+    timestamp__lt?: string;
+    /** Return first image with timestamp less than or equal to this value */
+    timestamp__lte?: string;
+    /** Return image at this exact timestamp */
+    timestamp?: string;
+    /** Return first image with timestamp greater than or equal to this value */
+    timestamp__gte?: string;
+    /** Return first image with timestamp greater than this value */
+    timestamp__gt?: string;
+    /** List of overlay IDs to include */
+    overlayId__in?: string[];
+    /**
+     * Include options for overlays.
+     * Valid values: overlayEmbedded, overlaySvgHeader
+     */
+    include?: string[];
+    /** Target width for the returned image (32-7680) */
+    targetWidth?: number;
+    /** Target height for the returned image (32-4320) */
+    targetHeight?: number;
+}
+
 /**
  * Get the redirect URI
  */
@@ -1010,6 +1199,91 @@ export declare interface ListCamerasParams {
     status__ne?: CameraStatus;
 }
 
+/**
+ * List media intervals (recording periods) for a device.
+ *
+ * @remarks
+ * Fetches a paginated list of time intervals for which recordings exist.
+ * Use this to find available recordings for a camera.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/listmedia).
+ *
+ * @param params - Required parameters including deviceId, type, mediaType, and startTimestamp
+ * @returns A Result containing a paginated list of media intervals or an error
+ *
+ * @example
+ * ```typescript
+ * import { listMedia } from 'een-api-toolkit'
+ *
+ * // Get video recordings from the last hour
+ * const { data, error } = await listMedia({
+ *   deviceId: 'camera-123',
+ *   type: 'preview',
+ *   mediaType: 'video',
+ *   startTimestamp: new Date(Date.now() - 3600000).toISOString()
+ * })
+ *
+ * if (data) {
+ *   console.log(`Found ${data.results.length} recording intervals`)
+ *   data.results.forEach(interval => {
+ *     console.log(`${interval.startTimestamp} - ${interval.endTimestamp}`)
+ *   })
+ * }
+ * ```
+ *
+ * @category Media
+ */
+export declare function listMedia(params: ListMediaParams): Promise<Result<PaginatedResult<MediaInterval>>>;
+
+/**
+ * Parameters for listing media intervals.
+ *
+ * @remarks
+ * Used to query recording intervals for a device.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/listmedia).
+ *
+ * @example
+ * ```typescript
+ * import { listMedia } from 'een-api-toolkit'
+ *
+ * // Get video recordings from the last hour
+ * const { data } = await listMedia({
+ *   deviceId: 'camera-123',
+ *   type: 'preview',
+ *   mediaType: 'video',
+ *   startTimestamp: new Date(Date.now() - 3600000).toISOString()
+ * })
+ * ```
+ *
+ * @category Media
+ */
+export declare interface ListMediaParams {
+    /** The ID of the device (camera) - required */
+    deviceId: string;
+    /** Stream type (preview or main) - required */
+    type: MediaStreamType;
+    /** Media type (video or image) - required */
+    mediaType: MediaType;
+    /** Minimum timestamp from which to list recordings (ISO 8601) - required */
+    startTimestamp: string;
+    /** Maximum timestamp until which to list recordings (ISO 8601) */
+    endTimestamp?: string;
+    /** If true, coalesce connected intervals into a single interval (default: true) */
+    coalesce?: boolean;
+    /**
+     * Additional fields to include in the response.
+     * Valid values: flvUrl, rtspUrl, rtspsUrl, hlsUrl, multipartUrl, mp4Url, wsLiveUrl
+     */
+    include?: string[];
+    /** Token for fetching a specific page */
+    pageToken?: string;
+    /** Number of results per page */
+    pageSize?: number;
+}
+
 /**
  * Parameters for listing users.
  *
@@ -1037,6 +1311,80 @@ export declare interface ListUsersParams {
     include?: string[];
 }
 
+/**
+ * Result of getting a live image.
+ *
+ * @remarks
+ * Contains the image data as a base64 data URL and metadata from response headers.
+ *
+ * @category Media
+ */
+export declare interface LiveImageResult {
+    /** Base64 encoded image data URL (data:image/jpeg;base64,...) */
+    imageData: string;
+    /** Timestamp of the image (from X-Een-Timestamp header) */
+    timestamp: string | null;
+    /** Token to fetch the previous image (from X-Een-PrevToken header) */
+    prevToken: string | null;
+}
+
+/**
+ * Media interval from EEN API v3.0.
+ *
+ * @remarks
+ * Represents a time interval for which recordings exist.
+ *
+ * @category Media
+ */
+export declare interface MediaInterval {
+    /** Stream type (preview or main) */
+    type: MediaStreamType;
+    /** The device ID that generated the media */
+    deviceId: string;
+    /** Type of media contained (video or image) */
+    mediaType: MediaType;
+    /** Start time of the media interval (ISO 8601) */
+    startTimestamp: string;
+    /** End time of the media interval (ISO 8601) */
+    endTimestamp: string;
+    /** Flash video URL (if requested via include) */
+    flvUrl?: string | null;
+    /** RTSP URL (if requested via include) */
+    rtspUrl?: string;
+    /** RTSPS URL (if requested via include) */
+    rtspsUrl?: string;
+    /** HLS URL (if requested via include) */
+    hlsUrl?: string | null;
+    /** Multipart URL (if requested via include) */
+    multipartUrl?: string;
+    /** MP4 URL (if requested via include) */
+    mp4Url?: string | null;
+    /** WebSocket live URL (if requested via include) */
+    wsLiveUrl?: string;
+}
+
+/**
+ * Stream type values from EEN API v3.0.
+ *
+ * @remarks
+ * Indicates the quality/type of the media stream.
+ * - `preview`: Low resolution, low framerate stream
+ * - `main`: High resolution stream
+ *
+ * @category Media
+ */
+export declare type MediaStreamType = 'preview' | 'main';
+
+/**
+ * Media type values from EEN API v3.0.
+ *
+ * @remarks
+ * Indicates the type of media content.
+ *
+ * @category Media
+ */
+export declare type MediaType = 'video' | 'image';
+
 /**
  * Paginated response from list operations.
  *
@@ -1088,6 +1436,27 @@ export declare interface PaginationParams {
     pageToken?: string;
 }
 
+/**
+ * Result of getting a recorded image.
+ *
+ * @remarks
+ * Contains the image data as a base64 data URL and metadata from response headers.
+ *
+ * @category Media
+ */
+export declare interface RecordedImageResult {
+    /** Base64 encoded image data URL (data:image/jpeg;base64,...) */
+    imageData: string;
+    /** Timestamp of the image (from X-Een-Timestamp header) */
+    timestamp: string | null;
+    /** Token to fetch the next image (from X-Een-NextToken header) */
+    nextToken: string | null;
+    /** Token to fetch the previous image (from X-Een-PrevToken header) */
+    prevToken: string | null;
+    /** SVG overlay data (from X-Een-OverlaySvg header, if requested) */
+    overlaySvg: string | null;
+}
+
 /**
  * Refresh the access token using stored refresh token
  */