een-api-toolkit 0.3.28 → 0.3.35

package/dist/index.d.ts

@@ -384,6 +384,13 @@ export declare interface Camera {
     updatedAt?: string;
 }
 
+/**
+ * Camera aspect ratio values for layout settings.
+ *
+ * @category Layouts
+ */
+export declare type CameraAspectRatio = '16x9' | '4x3';
+
 /**
  * Device information for a camera.
  *
@@ -495,6 +502,25 @@ export declare interface CameraShareDetails {
  */
 export declare type CameraStatus = 'online' | 'offline' | 'deviceOffline' | 'bridgeOffline' | 'invalidCredentials' | 'error' | 'streaming' | 'registered' | 'attaching' | 'initializing';
 
+/**
+ * Camera status counts for layout resource summaries.
+ *
+ * @remarks
+ * Used in resourceStatusCounts to show aggregated camera statuses.
+ *
+ * @category Layouts
+ */
+export declare interface CameraStatusCounts {
+    /** Number of online cameras */
+    online?: number;
+    /** Number of offline cameras */
+    offline?: number;
+    /** Number of cameras in error state */
+    error?: number;
+    /** Number of cameras with other statuses */
+    other?: number;
+}
+
 /**
  * Stream URLs for camera media.
  *
@@ -649,6 +675,83 @@ export declare interface CreateEventSubscriptionParams {
     filters: FilterCreate[];
 }
 
+/**
+ * Create a new layout.
+ *
+ * @remarks
+ * Creates a layout via `POST /api/v3.0/layouts`. Name and settings are required.
+ * Panes can be added during creation or later via `updateLayout()`.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/createlayout).
+ *
+ * @param params - The layout configuration
+ * @returns A Result containing the created layout or an error
+ *
+ * @example
+ * ```typescript
+ * import { createLayout } from 'een-api-toolkit'
+ *
+ * const { data, error } = await createLayout({
+ *   name: 'Main Lobby View',
+ *   settings: {
+ *     showCameraBorder: true,
+ *     showCameraName: true,
+ *     cameraAspectRatio: '16x9',
+ *     paneColumns: 3
+ *   },
+ *   panes: [
+ *     { id: 1, name: 'Entrance', type: 'preview', size: 1, cameraId: 'cam-123' },
+ *     { id: 2, name: 'Lobby', type: 'preview', size: 2, cameraId: 'cam-456' }
+ *   ]
+ * })
+ *
+ * if (data) {
+ *   console.log(`Created layout: ${data.id}`)
+ * }
+ * ```
+ *
+ * @category Layouts
+ */
+export declare function createLayout(params: CreateLayoutParams): Promise<Result<Layout>>;
+
+/**
+ * Parameters for creating a new layout.
+ *
+ * @remarks
+ * Name and settings are required. Panes can be added during creation
+ * or later via update.
+ *
+ * @example
+ * ```typescript
+ * import { createLayout } from 'een-api-toolkit'
+ *
+ * const { data, error } = await createLayout({
+ *   name: 'Main Lobby View',
+ *   settings: {
+ *     showCameraBorder: true,
+ *     showCameraName: true,
+ *     cameraAspectRatio: '16x9',
+ *     paneColumns: 3
+ *   },
+ *   panes: [
+ *     { id: 1, name: 'Entrance', type: 'preview', size: 1, cameraId: 'cam-123' },
+ *     { id: 2, name: 'Lobby', type: 'preview', size: 2, cameraId: 'cam-456' }
+ *   ]
+ * })
+ * ```
+ *
+ * @category Layouts
+ */
+export declare interface CreateLayoutParams {
+    /** Display name for the layout (required) */
+    name: string;
+    /** Display settings for the layout (required) */
+    settings: LayoutSettings;
+    /** Initial panes to add to the layout (optional) */
+    panes?: LayoutPane[];
+}
+
 /**
  * Delete an event subscription.
  *
@@ -678,6 +781,40 @@ export declare interface CreateEventSubscriptionParams {
  */
 export declare function deleteEventSubscription(subscriptionId: string): Promise<Result<void>>;
 
+/**
+ * Delete a layout.
+ *
+ * @remarks
+ * Deletes a layout via `DELETE /api/v3.0/layouts/{layoutId}`.
+ * Returns void on success (204 No Content).
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/deletelayout).
+ *
+ * @param layoutId - The unique identifier of the layout to delete
+ * @returns A Result containing void on success or an error
+ *
+ * @example
+ * ```typescript
+ * import { deleteLayout } from 'een-api-toolkit'
+ *
+ * const { error } = await deleteLayout('layout-123')
+ *
+ * if (error) {
+ *   if (error.code === 'NOT_FOUND') {
+ *     console.log('Layout already deleted')
+ *   } else {
+ *     console.error('Delete failed:', error.message)
+ *   }
+ * } else {
+ *   console.log('Layout deleted successfully')
+ * }
+ * ```
+ *
+ * @category Layouts
+ */
+export declare function deleteLayout(layoutId: string): Promise<Result<void>>;
+
 /**
  * Delivery configuration (union type).
  *
@@ -1732,6 +1869,118 @@ export declare interface GetEventParams {
  */
 export declare function getEventSubscription(subscriptionId: string): Promise<Result<EventSubscription>>;
 
+/**
+ * Get a specific layout by ID.
+ *
+ * @remarks
+ * Fetches a single layout from `/api/v3.0/layouts/{layoutId}`. Use the `include`
+ * parameter to request additional fields.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/getlayout).
+ *
+ * @param layoutId - The unique identifier of the layout to fetch
+ * @param params - Optional parameters (e.g., include additional fields)
+ * @returns A Result containing the layout or an error
+ *
+ * @example
+ * ```typescript
+ * import { getLayout } from 'een-api-toolkit'
+ *
+ * const { data, error } = await getLayout('layout-123')
+ *
+ * if (error) {
+ *   if (error.code === 'NOT_FOUND') {
+ *     console.log('Layout not found')
+ *   }
+ *   return
+ * }
+ *
+ * console.log(`Layout: ${data.name} (${data.panes.length} panes)`)
+ *
+ * // With additional fields
+ * const { data: layoutWithDetails } = await getLayout('layout-123', {
+ *   include: ['effectivePermissions', 'resourceStatusCounts']
+ * })
+ * ```
+ *
+ * @category Layouts
+ */
+export declare function getLayout(layoutId: string, params?: GetLayoutParams): Promise<Result<Layout>>;
+
+/**
+ * Valid include options for getting a single layout.
+ *
+ * @category Layouts
+ */
+export declare type GetLayoutInclude = 'effectivePermissions' | 'resourceCounts' | 'resourceStatusCounts';
+
+/**
+ * Parameters for getting a single layout.
+ *
+ * @remarks
+ * Controls which additional fields to include in the response.
+ *
+ * @example
+ * ```typescript
+ * import { getLayout } from 'een-api-toolkit'
+ *
+ * const { data } = await getLayout('layout-123', {
+ *   include: ['effectivePermissions', 'resourceStatusCounts']
+ * })
+ * ```
+ *
+ * @category Layouts
+ */
+export declare interface GetLayoutParams {
+    /** Additional fields to include in the response */
+    include?: GetLayoutInclude[];
+}
+
+/**
+ * List layouts with optional pagination and filtering.
+ *
+ * @remarks
+ * Fetches a paginated list of layouts from `/api/v3.0/layouts`. Supports
+ * filtering options for name, search, and more.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/listlayouts).
+ *
+ * @param params - Optional pagination and filtering parameters
+ * @returns A Result containing a paginated list of layouts or an error
+ *
+ * @example
+ * ```typescript
+ * import { getLayouts } from 'een-api-toolkit'
+ *
+ * // Basic usage
+ * const { data, error } = await getLayouts()
+ * if (data) {
+ *   console.log(`Found ${data.results.length} layouts`)
+ * }
+ *
+ * // With filters
+ * const { data } = await getLayouts({
+ *   pageSize: 50,
+ *   include: ['resourceCounts', 'effectivePermissions']
+ * })
+ *
+ * // Fetch all layouts
+ * let allLayouts: Layout[] = []
+ * let pageToken: string | undefined
+ * do {
+ *   const { data, error } = await getLayouts({ pageSize: 100, pageToken })
+ *   if (error) break
+ *   allLayouts.push(...data.results)
+ *   pageToken = data.nextPageToken
+ * } while (pageToken)
+ * ```
+ *
+ * @category Layouts
+ */
+export declare function getLayouts(params?: ListLayoutsParams): Promise<Result<PaginatedResult<Layout>>>;
+
 /**
  * Get a live image from a camera.
  *
@@ -2196,6 +2445,145 @@ export declare function initEenToolkit(options?: EenToolkitConfig): void;
  */
 export declare function initMediaSession(): Promise<Result<MediaSessionResult>>;
 
+/**
+ * Layout entity from EEN API v3.0.
+ *
+ * @remarks
+ * Represents a layout (grouping of cameras) in the Eagle Eye Networks platform.
+ * Layouts organize multiple camera views into a grid for monitoring.
+ *
+ * For more details on layout management, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/listlayouts).
+ *
+ * @example
+ * ```typescript
+ * import { getLayouts, type Layout } from 'een-api-toolkit'
+ *
+ * const { data, error } = await getLayouts()
+ * if (data) {
+ *   data.results.forEach((layout: Layout) => {
+ *     console.log(`${layout.name}: ${layout.panes.length} cameras`)
+ *   })
+ * }
+ * ```
+ *
+ * @category Layouts
+ */
+export declare interface Layout {
+    /** Unique identifier for the layout */
+    id: string;
+    /** Display name of the layout */
+    name: string;
+    /** ID of the account this layout belongs to */
+    accountId: string;
+    /** Array of panes (camera positions) in the layout */
+    panes: LayoutPane[];
+    /** Display settings for the layout */
+    settings: LayoutSettings;
+    /** Permissions the current user has on this layout (optional, via include) */
+    effectivePermissions?: LayoutPermissions;
+    /** Count of resources in the layout (optional, via include) */
+    resourceCounts?: {
+        cameras?: number;
+    };
+    /** Status counts of cameras in the layout (optional, via include) */
+    resourceStatusCounts?: {
+        cameras?: CameraStatusCounts;
+    };
+    /** Search relevance score when using q parameter */
+    qRelevance?: number;
+}
+
+/**
+ * A single pane within a layout.
+ *
+ * @remarks
+ * Represents one camera view position in the layout grid.
+ *
+ * @category Layouts
+ */
+export declare interface LayoutPane {
+    /**
+     * Unique identifier for the pane within the layout.
+     *
+     * @remarks
+     * - Must be unique within the same layout (no duplicate IDs)
+     * - IDs are client-managed; you assign them when creating/updating panes
+     * - Can be reused after a pane is deleted from the layout
+     * - Typically assigned sequentially (0, 1, 2, ...) but any unique number works
+     */
+    id: number;
+    /** Display name for the pane */
+    name: string;
+    /** Type of preview to display */
+    type: LayoutPaneType;
+    /** Size of the pane in the grid (1-3) */
+    size: LayoutPaneSize;
+    /** ID of the camera to display in this pane */
+    cameraId: string;
+    /** ID of composite preview if using compositePreview type */
+    compositeId?: string | null;
+}
+
+/**
+ * Layout pane size values.
+ *
+ * @remarks
+ * Controls how much space the pane takes in the grid.
+ * - 1: Normal size (1x1)
+ * - 2: Medium size (2x2)
+ * - 3: Large size (3x3)
+ *
+ * @category Layouts
+ */
+export declare type LayoutPaneSize = 1 | 2 | 3;
+
+/**
+ * Layout pane type values.
+ *
+ * @remarks
+ * Defines how the pane displays camera content.
+ *
+ * @category Layouts
+ */
+export declare type LayoutPaneType = 'preview' | 'compositePreview';
+
+/**
+ * Permissions for layout operations.
+ *
+ * @remarks
+ * Indicates what actions the current user can perform on a layout.
+ *
+ * @category Layouts
+ */
+export declare interface LayoutPermissions {
+    /** Whether the user can read the layout */
+    read?: boolean;
+    /** Whether the user can edit the layout */
+    edit?: boolean;
+    /** Whether the user can delete the layout */
+    delete?: boolean;
+}
+
+/**
+ * Layout display settings.
+ *
+ * @remarks
+ * Controls how cameras are displayed within the layout.
+ *
+ * @category Layouts
+ */
+export declare interface LayoutSettings {
+    /** Whether to show borders around camera panes */
+    showCameraBorder: boolean;
+    /** Whether to show camera names as overlays */
+    showCameraName: boolean;
+    /** Aspect ratio for camera displays */
+    cameraAspectRatio: CameraAspectRatio;
+    /** Number of columns in the layout grid (1-6) */
+    paneColumns: number;
+}
+
 /**
  * List alerts with optional filters and pagination.
  *
@@ -2962,6 +3350,79 @@ export declare interface ListFeedsResult {
     totalSize?: number;
 }
 
+/**
+ * Valid include options for listing layouts.
+ *
+ * @category Layouts
+ */
+export declare type ListLayoutsInclude = 'effectivePermissions' | 'resourceCounts' | 'resourceStatusCounts' | 'qRelevance';
+
+/**
+ * Parameters for listing layouts.
+ *
+ * @remarks
+ * Supports extensive 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/listlayouts).
+ *
+ * @example
+ * ```typescript
+ * import { getLayouts } from 'een-api-toolkit'
+ *
+ * // Get layouts with pagination
+ * const { data } = await getLayouts({
+ *   pageSize: 50,
+ *   include: ['resourceCounts', 'effectivePermissions']
+ * })
+ *
+ * // Search layouts by name
+ * const { data: searchResults } = await getLayouts({
+ *   q: 'lobby',
+ *   qRelevance__gte: 0.5
+ * })
+ *
+ * // Filter by name
+ * const { data: filtered } = await getLayouts({
+ *   name__contains: 'entrance'
+ * })
+ * ```
+ *
+ * @category Layouts
+ */
+export declare interface ListLayoutsParams {
+    /** 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?: ListLayoutsInclude[];
+    /** Fields to sort by (prefix with - for descending, + for ascending) */
+    sort?: ListLayoutsSort[];
+    /** Filter by exact name */
+    name?: string;
+    /** Filter by names (any match) */
+    name__in?: string[];
+    /** Filter by name containing substring (case-insensitive) */
+    name__contains?: string;
+    /** Filter by layout IDs */
+    id__in?: string[];
+    /** Filter by bridge ID of cameras in layout panes */
+    'layoutPanes.cameras.bridgeId'?: string;
+    /** Full-text search query */
+    q?: string;
+    /** Minimum search relevance score (0.0 to 1.0) */
+    qRelevance__gte?: number;
+}
+
+/**
+ * Valid sort options for listing layouts.
+ *
+ * @category Layouts
+ */
+export declare type ListLayoutsSort = '+name' | '-name' | '+rotationOrder' | '+qRelevance' | '-qRelevance';
+
 /**
  * List media intervals (recording periods) for a device.
  *
@@ -3723,6 +4184,106 @@ export declare interface TokenResponse {
     sessionId: string;
 }
 
+/**
+ * Update an existing layout.
+ *
+ * @remarks
+ * Updates a layout via `PATCH /api/v3.0/layouts/{layoutId}`. Only provided
+ * fields will be updated. Returns void on success (204 No Content).
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/updatelayout).
+ *
+ * @param layoutId - The unique identifier of the layout to update
+ * @param params - The fields to update
+ * @returns A Result containing void on success or an error
+ *
+ * @example
+ * ```typescript
+ * import { updateLayout } from 'een-api-toolkit'
+ *
+ * // Update name only
+ * const { error } = await updateLayout('layout-123', {
+ *   name: 'Updated Layout Name'
+ * })
+ *
+ * // Update settings
+ * const { error } = await updateLayout('layout-123', {
+ *   settings: {
+ *     paneColumns: 4,
+ *     showCameraName: false
+ *   }
+ * })
+ *
+ * // Replace panes
+ * const { error } = await updateLayout('layout-123', {
+ *   panes: [
+ *     { id: 1, name: 'New Pane', type: 'preview', size: 1, cameraId: 'cam-789' }
+ *   ]
+ * })
+ *
+ * if (error) {
+ *   console.error('Update failed:', error.message)
+ * }
+ * ```
+ *
+ * @category Layouts
+ */
+export declare function updateLayout(layoutId: string, params: UpdateLayoutParams): Promise<Result<void>>;
+
+/**
+ * Parameters for updating an existing layout.
+ *
+ * @remarks
+ * All fields are optional. Only provided fields will be updated.
+ * For settings, you can provide partial updates.
+ *
+ * @example
+ * ```typescript
+ * import { updateLayout } from 'een-api-toolkit'
+ *
+ * // Update name only
+ * const { error } = await updateLayout('layout-123', {
+ *   name: 'Updated Layout Name'
+ * })
+ *
+ * // Update settings
+ * const { error } = await updateLayout('layout-123', {
+ *   settings: {
+ *     paneColumns: 4,
+ *     showCameraName: false
+ *   }
+ * })
+ *
+ * // Replace panes
+ * const { error } = await updateLayout('layout-123', {
+ *   panes: [
+ *     { id: 1, name: 'New Pane', type: 'preview', size: 1, cameraId: 'cam-789' }
+ *   ]
+ * })
+ * ```
+ *
+ * @category Layouts
+ */
+export declare interface UpdateLayoutParams {
+    /** New display name for the layout */
+    name?: string;
+    /**
+     * Updated display settings.
+     *
+     * @remarks
+     * The EEN API supports partial PATCH updates for settings. You only need to
+     * include the fields you want to change; other fields retain their current values.
+     *
+     * @example
+     * // Only update paneColumns, keeping other settings unchanged
+     * { settings: { paneColumns: 4 } }
+     */
+    settings?: Partial<LayoutSettings>;
+    /** New panes array (replaces existing panes entirely) */
+    panes?: LayoutPane[];
+}
+
 /**
  * Pinia store for authentication state management
  */