een-api-toolkit 0.1.2 → 0.1.7

package/dist/index.d.ts

@@ -2,6 +2,145 @@ import { ComputedRef } from 'vue';
 import { Ref } from 'vue';
 import { StoreDefinition } from 'pinia';
 
+/**
+ * Bridge entity from EEN API v3.0.
+ *
+ * @remarks
+ * Represents a bridge in the Eagle Eye Networks platform. Bridges are
+ * physical devices that connect cameras to the cloud. They aggregate
+ * video streams from multiple cameras and provide network connectivity.
+ *
+ * For more details on bridge management, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/listbridges).
+ *
+ * @example
+ * ```typescript
+ * import { getBridges, type Bridge } from 'een-api-toolkit'
+ *
+ * const { data, error } = await getBridges({ include: ['status'] })
+ * if (data) {
+ *   data.results.forEach((bridge: Bridge) => {
+ *     console.log(`${bridge.name}: ${bridge.status}`)
+ *   })
+ * }
+ * ```
+ *
+ * @category Bridges
+ */
+export declare interface Bridge {
+    /** Unique identifier for the bridge */
+    id: string;
+    /** Display name of the bridge */
+    name: string;
+    /** ID of the account this bridge belongs to */
+    accountId: string;
+    /** ID of the location where the bridge is installed */
+    locationId?: string | null;
+    /** Globally unique identifier */
+    guid?: string;
+    /** Timezone of the bridge location (IANA timezone name) */
+    timezone?: string;
+    /**
+     * Current status of the bridge.
+     *
+     * @remarks
+     * The API may return status as either a string or an object
+     * depending on the `include` parameters.
+     */
+    status?: BridgeStatus | {
+        connectionStatus?: BridgeStatus;
+    };
+    /** Tags assigned to this bridge for organization */
+    tags?: string[];
+    /** Device information (make, model, firmware) */
+    deviceInfo?: BridgeDeviceInfo;
+    /** Network information (IP addresses, MAC) */
+    networkInfo?: BridgeNetworkInfo;
+    /** Physical position of the bridge */
+    devicePosition?: BridgeDevicePosition;
+    /** Number of cameras connected to this bridge */
+    cameraCount?: number;
+    /** ISO 8601 timestamp when the bridge was created */
+    createdAt?: string;
+    /** ISO 8601 timestamp when the bridge was last updated */
+    updatedAt?: string;
+}
+
+/**
+ * Device information for a bridge.
+ *
+ * @remarks
+ * Contains hardware and firmware details about the physical bridge device.
+ *
+ * @category Bridges
+ */
+export declare interface BridgeDeviceInfo {
+    /** Bridge manufacturer */
+    make?: string;
+    /** Bridge model */
+    model?: string;
+    /** Firmware version */
+    firmwareVersion?: string;
+    /** Serial number */
+    serialNumber?: string;
+    /** Hardware version */
+    hardwareVersion?: string;
+}
+
+/**
+ * Bridge position/location data.
+ *
+ * @remarks
+ * Physical location of the bridge.
+ *
+ * @category Bridges
+ */
+export declare interface BridgeDevicePosition {
+    /** Latitude coordinate */
+    latitude?: number;
+    /** Longitude coordinate */
+    longitude?: number;
+    /** Altitude in meters */
+    altitude?: number;
+    /** Floor level */
+    floor?: number;
+    /** Direction bridge is facing (0-360 degrees) */
+    azimuth?: number;
+}
+
+/**
+ * Network information for a bridge.
+ *
+ * @remarks
+ * Contains network connectivity details for the bridge.
+ *
+ * @category Bridges
+ */
+export declare interface BridgeNetworkInfo {
+    /** Local IP address of the bridge */
+    localIpAddress?: string;
+    /** Public IP address of the bridge */
+    publicIpAddress?: string;
+    /** MAC address */
+    macAddress?: string;
+    /** Subnet mask */
+    subnetMask?: string;
+    /** Default gateway */
+    gateway?: string;
+    /** DNS servers */
+    dnsServers?: string[];
+}
+
+/**
+ * Bridge status values from EEN API v3.0.
+ *
+ * @remarks
+ * Indicates the current operational state of a bridge.
+ *
+ * @category Bridges
+ */
+export declare type BridgeStatus = 'online' | 'offline' | 'error' | 'idle' | 'registered' | 'attaching' | 'initializing';
+
 /**
  * Camera entity from EEN API v3.0.
  *
@@ -303,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 */
 
@@ -317,6 +456,119 @@ export declare function getAccessToken(code: string): Promise<Result<TokenRespon
  */
 export declare function getAuthUrl(): string;
 
+/**
+ * Get a specific bridge by ID.
+ *
+ * @remarks
+ * Fetches a single bridge from `/api/v3.0/bridges/{bridgeId}`. Use the `include`
+ * parameter to request additional fields.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/getbridge).
+ *
+ * @param bridgeId - The unique identifier of the bridge to fetch
+ * @param params - Optional parameters (e.g., include additional fields)
+ * @returns A Result containing the bridge or an error
+ *
+ * @example
+ * ```typescript
+ * import { getBridge } from 'een-api-toolkit'
+ *
+ * const { data, error } = await getBridge('bridge-123')
+ *
+ * if (error) {
+ *   if (error.code === 'NOT_FOUND') {
+ *     console.log('Bridge not found')
+ *   }
+ *   return
+ * }
+ *
+ * console.log(`Bridge: ${data.name} (${data.status})`)
+ *
+ * // With additional fields
+ * const { data: bridgeWithDetails } = await getBridge('bridge-123', {
+ *   include: ['deviceInfo', 'networkInfo', 'status']
+ * })
+ * ```
+ *
+ * @category Bridges
+ */
+export declare function getBridge(bridgeId: string, params?: GetBridgeParams): Promise<Result<Bridge>>;
+
+/**
+ * Parameters for getting a single bridge.
+ *
+ * @remarks
+ * Valid include values: account, status, locationSummary, deviceAddress,
+ * timeZone, notes, tags, devicePosition, networkInfo, deviceInfo,
+ * effectivePermissions, firmware
+ *
+ * @example
+ * ```typescript
+ * import { getBridge } from 'een-api-toolkit'
+ *
+ * const { data } = await getBridge('bridge-123', {
+ *   include: ['deviceInfo', 'status', 'networkInfo']
+ * })
+ * ```
+ *
+ * @category Bridges
+ */
+export declare interface GetBridgeParams {
+    /**
+     * Additional fields to include in the response.
+     * Valid values: account, status, locationSummary, deviceAddress,
+     * timeZone, notes, tags, devicePosition, networkInfo, deviceInfo,
+     * effectivePermissions, firmware
+     */
+    include?: string[];
+}
+
+/**
+ * List bridges with optional pagination and filtering.
+ *
+ * @remarks
+ * Fetches a paginated list of bridges from `/api/v3.0/bridges`. Supports
+ * filtering options for location, status, tags, and more.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/listbridges).
+ *
+ * @param params - Optional pagination and filtering parameters
+ * @returns A Result containing a paginated list of bridges or an error
+ *
+ * @example
+ * ```typescript
+ * import { getBridges } from 'een-api-toolkit'
+ *
+ * // Basic usage
+ * const { data, error } = await getBridges()
+ * if (data) {
+ *   console.log(`Found ${data.results.length} bridges`)
+ * }
+ *
+ * // With filters
+ * const { data } = await getBridges({
+ *   pageSize: 50,
+ *   status__in: ['online'],
+ *   include: ['deviceInfo', 'networkInfo']
+ * })
+ *
+ * // Fetch all bridges
+ * let allBridges: Bridge[] = []
+ * let pageToken: string | undefined
+ * do {
+ *   const { data, error } = await getBridges({ pageSize: 100, pageToken })
+ *   if (error) break
+ *   allBridges.push(...data.results)
+ *   pageToken = data.nextPageToken
+ * } while (pageToken)
+ * ```
+ *
+ * @category Bridges
+ */
+export declare function getBridges(params?: ListBridgesParams): Promise<Result<PaginatedResult<Bridge>>>;
+
 /**
  * Get a specific camera by ID.
  *
@@ -472,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
  */
@@ -597,6 +1038,70 @@ export declare function handleAuthCallback(code: string, state: string): Promise
  */
 export declare function initEenToolkit(options?: EenToolkitConfig): void;
 
+/**
+ * Parameters for listing bridges.
+ *
+ * @remarks
+ * Supports filtering options matching the EEN API v3.0.
+ * All array parameters are sent as comma-separated values.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/listbridges).
+ *
+ * @example
+ * ```typescript
+ * import { getBridges } from 'een-api-toolkit'
+ *
+ * // Get online bridges with pagination
+ * const { data } = await getBridges({
+ *   pageSize: 50,
+ *   status__in: ['online'],
+ *   include: ['deviceInfo', 'networkInfo']
+ * })
+ *
+ * // Filter by location
+ * const { data: filtered } = await getBridges({
+ *   locationId__in: ['loc-123']
+ * })
+ * ```
+ *
+ * @category Bridges
+ */
+export declare interface ListBridgesParams {
+    /** Number of results per page (default: 100, max: 1000) */
+    pageSize?: number;
+    /** Token for fetching a specific page */
+    pageToken?: string;
+    /** Additional fields to include in the response */
+    include?: string[];
+    /** Fields to sort by (prefix with - for descending) */
+    sort?: string[];
+    /** Filter by location IDs */
+    locationId__in?: string[];
+    /** Filter by tags (all tags must be present) */
+    tags__contains?: string[];
+    /** Filter by tags (any tag must be present) */
+    tags__any?: string[];
+    /** Filter by exact name */
+    name?: string;
+    /** Filter by name containing substring (case-insensitive) */
+    name__contains?: string;
+    /** Filter by exact names (any match) */
+    name__in?: string[];
+    /** Filter by bridge IDs */
+    id__in?: string[];
+    /** Exclude bridge IDs */
+    id__notIn?: string[];
+    /** Full-text search query */
+    q?: string;
+    /** Minimum search relevance score */
+    qRelevance__gte?: number;
+    /** Filter by status values (any match) */
+    status__in?: BridgeStatus[];
+    /** Filter by status not equal to */
+    status__ne?: BridgeStatus;
+}
+
 /**
  * Parameters for listing cameras.
  *
@@ -694,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.
  *
@@ -721,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.
  *
@@ -772,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
  */