een-api-toolkit 0.3.85 → 0.3.97

package/dist/index.d.ts

@@ -605,6 +605,25 @@ export declare interface Camera {
     rtspConnectionSettings?: CameraRtspConnectionSettings;
     /** Physical position of the camera */
     devicePosition?: CameraDevicePosition;
+    /** Capabilities of the camera (returned when `include: ['capabilities']` is requested) */
+    capabilities?: {
+        ptz?: {
+            /** Whether this camera supports PTZ controls */
+            capable?: boolean;
+            /** Whether this is a fisheye camera (not a true PTZ camera) */
+            fisheye?: boolean;
+            /** Whether the camera supports pan/tilt movements */
+            panTilt?: boolean;
+            /** Whether the camera supports zoom */
+            zoom?: boolean;
+            /** Whether the camera supports absolute position moves */
+            positionMove?: boolean;
+            /** Whether the camera supports directional moves */
+            directionMove?: boolean;
+            /** Whether the camera supports center-on moves */
+            centerOnMove?: boolean;
+        };
+    };
     /** List of enabled analytics on this camera */
     enabledAnalytics?: string[];
     /** Recording mode settings */
@@ -3861,6 +3880,62 @@ export declare function getNotification(notificationId: string): Promise<Result<
  */
 export declare function getProxyUrl(): string | undefined;
 
+/**
+ * Get the current PTZ position of a camera.
+ *
+ * @remarks
+ * Fetches the current pan, tilt, and zoom coordinates from
+ * `/api/v3.0/cameras/{cameraId}/ptz/position`.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/getptzposition).
+ *
+ * @param cameraId - The unique identifier of the PTZ camera
+ * @returns A Result containing the current PTZ position or an error
+ *
+ * @example
+ * ```typescript
+ * import { getPtzPosition } from 'een-api-toolkit'
+ *
+ * const { data, error } = await getPtzPosition('camera-123')
+ * if (data) {
+ *   console.log(`Pan: ${data.x}, Tilt: ${data.y}, Zoom: ${data.z}`)
+ * }
+ * ```
+ *
+ * @category PTZ
+ */
+export declare function getPtzPosition(cameraId: string): Promise<Result<PtzPositionResponse>>;
+
+/**
+ * Get PTZ settings for a camera, including presets and automation mode.
+ *
+ * @remarks
+ * Fetches PTZ configuration from `/api/v3.0/cameras/{cameraId}/ptz/settings`.
+ * Returns presets, home preset, automation mode, and auto-start delay.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/getptzsettings).
+ *
+ * @param cameraId - The unique identifier of the PTZ camera
+ * @returns A Result containing the PTZ settings or an error
+ *
+ * @example
+ * ```typescript
+ * import { getPtzSettings } from 'een-api-toolkit'
+ *
+ * const { data, error } = await getPtzSettings('camera-123')
+ * if (data) {
+ *   console.log('Mode:', data.mode)
+ *   console.log('Presets:', data.presets.length)
+ *   console.log('Home:', data.homePreset)
+ * }
+ * ```
+ *
+ * @category PTZ
+ */
+export declare function getPtzSettings(cameraId: string): Promise<Result<PtzSettings>>;
+
 /**
  * Get a recorded image from a camera.
  *
@@ -6259,6 +6334,39 @@ export declare type MetricActorType = 'bridge' | 'camera' | 'speaker' | 'account
  */
 export declare type MetricDataPoint = [number, number];
 
+/**
+ * Move a PTZ camera to a new position.
+ *
+ * @remarks
+ * Sends a movement command to a PTZ camera via
+ * `PUT /api/v3.0/cameras/{cameraId}/ptz/position`.
+ * Supports three move types: absolute position, relative direction, and center-on.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/updateptzposition).
+ *
+ * @param cameraId - The unique identifier of the PTZ camera
+ * @param move - The movement command (position, direction, or centerOn)
+ * @returns A Result containing void on success or an error
+ *
+ * @example
+ * ```typescript
+ * import { movePtz } from 'een-api-toolkit'
+ *
+ * // Move to absolute position
+ * await movePtz('camera-123', { moveType: 'position', x: 0.5, y: -0.3, z: 2.0 })
+ *
+ * // Move in a direction
+ * await movePtz('camera-123', { moveType: 'direction', direction: ['left'], stepSize: 'medium' })
+ *
+ * // Center on a point in the frame
+ * await movePtz('camera-123', { moveType: 'centerOn', relativeX: 0.75, relativeY: 0.5 })
+ * ```
+ *
+ * @category PTZ
+ */
+export declare function movePtz(cameraId: string, move: PtzMove): Promise<Result<void>>;
+
 /**
  * Notification entity from EEN API v3.0.
  *
@@ -6432,6 +6540,276 @@ export declare interface PlaySpeakerAudioClipSettings {
     volume?: number;
 }
 
+/**
+ * Center the camera on a point in the current frame.
+ *
+ * @remarks
+ * Uses relative coordinates within the current video frame
+ * to center the camera on a specific point. Useful for click-to-center
+ * functionality in video players.
+ * Both `relativeX` and `relativeY` must be in the range 0.0 to 1.0,
+ * where (0.0, 0.0) is the top-left corner and (1.0, 1.0) is the bottom-right.
+ *
+ * @example
+ * ```typescript
+ * // Center on the middle-right area of the frame
+ * const move: PtzCenterOnMove = {
+ *   moveType: 'centerOn',
+ *   relativeX: 0.75,
+ *   relativeY: 0.5
+ * }
+ * ```
+ *
+ * @category PTZ
+ */
+export declare interface PtzCenterOnMove {
+    /** Must be 'centerOn' */
+    moveType: 'centerOn';
+    /** Horizontal position in frame (0.0 = left, 1.0 = right) */
+    relativeX: number;
+    /** Vertical position in frame (0.0 = top, 1.0 = bottom) */
+    relativeY: number;
+}
+
+/**
+ * Directional movement options for PTZ cameras.
+ *
+ * @category PTZ
+ */
+export declare type PtzDirection = 'up' | 'down' | 'left' | 'right' | 'in' | 'out';
+
+/**
+ * Move in a relative direction with optional step size.
+ *
+ * @remarks
+ * Moves the camera in one or more directions relative to its current position.
+ * Multiple directions can be combined (e.g., up + left for diagonal movement).
+ *
+ * @example
+ * ```typescript
+ * const move: PtzDirectionMove = {
+ *   moveType: 'direction',
+ *   direction: ['up', 'left'],
+ *   stepSize: 'medium'
+ * }
+ * ```
+ *
+ * @category PTZ
+ */
+export declare interface PtzDirectionMove {
+    /** Must be 'direction' */
+    moveType: 'direction';
+    /** One or more directions to move */
+    direction: PtzDirection[];
+    /** Size of each movement step (default: medium) */
+    stepSize?: PtzStepSize;
+}
+
+/**
+ * PTZ automation mode.
+ *
+ * @remarks
+ * - `homeReturn` - Camera returns to the home preset after a period of inactivity
+ * - `tour` - Camera cycles through presets automatically
+ * - `manualOnly` - No automatic movement; camera stays where positioned
+ *
+ * @category PTZ
+ */
+export declare type PtzMode = 'homeReturn' | 'tour' | 'manualOnly';
+
+/**
+ * Discriminated union of all PTZ move types.
+ *
+ * @remarks
+ * Use the `moveType` field to discriminate between the three movement types.
+ *
+ * @example
+ * ```typescript
+ * import { movePtz, type PtzMove } from 'een-api-toolkit'
+ *
+ * // Position move
+ * await movePtz('camera-id', { moveType: 'position', x: 0.5, y: 0.0, z: 1.0 })
+ *
+ * // Direction move
+ * await movePtz('camera-id', { moveType: 'direction', direction: ['left'], stepSize: 'small' })
+ *
+ * // Center-on move
+ * await movePtz('camera-id', { moveType: 'centerOn', relativeX: 0.5, relativeY: 0.5 })
+ * ```
+ *
+ * @category PTZ
+ */
+export declare type PtzMove = PtzPositionMove | PtzDirectionMove | PtzCenterOnMove;
+
+/**
+ * Types of PTZ movement commands.
+ *
+ * @remarks
+ * - `position` - Move to absolute coordinates (x, y, z)
+ * - `direction` - Move in relative directions (up, down, left, right, in, out)
+ * - `centerOn` - Center the camera view on a point in the current frame
+ *
+ * @category PTZ
+ */
+export declare type PtzMoveType = 'position' | 'direction' | 'centerOn';
+
+/**
+ * Pan/Tilt/Zoom position coordinates for movement commands.
+ *
+ * @remarks
+ * Used when specifying target positions in movement commands.
+ * Values are optional since you may want to move only one axis at a time.
+ *
+ * @category PTZ
+ */
+export declare interface PtzPosition {
+    /** Pan position (horizontal rotation) */
+    x?: number;
+    /** Tilt position (vertical rotation) */
+    y?: number;
+    /** Zoom level */
+    z?: number;
+}
+
+/**
+ * Move to absolute PTZ coordinates.
+ *
+ * @remarks
+ * Moves the camera to specific x, y, z position values.
+ * At least one coordinate (x, y, or z) should be provided for a meaningful move.
+ *
+ * @example
+ * ```typescript
+ * const move: PtzPositionMove = {
+ *   moveType: 'position',
+ *   x: 0.5,
+ *   y: -0.3,
+ *   z: 2.0
+ * }
+ * ```
+ *
+ * @category PTZ
+ */
+export declare interface PtzPositionMove {
+    /** Must be 'position' */
+    moveType: 'position';
+    /** Target pan position */
+    x?: number;
+    /** Target tilt position */
+    y?: number;
+    /** Target zoom level */
+    z?: number;
+}
+
+/**
+ * PTZ position as returned by the API (all fields present).
+ *
+ * @remarks
+ * When reading the current camera position via `getPtzPosition()`, the API
+ * always returns all three coordinates. This type extends `PtzPosition` with
+ * required fields for type safety at response sites.
+ *
+ * @category PTZ
+ */
+export declare interface PtzPositionResponse {
+    /** Pan position (horizontal rotation) */
+    x: number;
+    /** Tilt position (vertical rotation) */
+    y: number;
+    /** Zoom level */
+    z: number;
+}
+
+/**
+ * A saved PTZ preset position.
+ *
+ * @remarks
+ * Presets allow quick navigation to saved camera positions.
+ *
+ * @category PTZ
+ */
+export declare interface PtzPreset {
+    /** Human-readable name for this preset */
+    name: string;
+    /** The saved position coordinates (always has x, y, z from the API) */
+    position: PtzPositionResponse;
+    /** Time the camera stays at this preset (in seconds) during tour mode */
+    timeAtPreset: number;
+}
+
+/**
+ * PTZ camera settings including presets and automation mode.
+ *
+ * @remarks
+ * Contains the full PTZ configuration for a camera: saved presets,
+ * the designated home preset, automation mode, and auto-start delay.
+ *
+ * @example
+ * ```typescript
+ * import { getPtzSettings } from 'een-api-toolkit'
+ *
+ * const { data, error } = await getPtzSettings('camera-id')
+ * if (data) {
+ *   console.log('Mode:', data.mode)
+ *   console.log('Presets:', data.presets.map(p => p.name))
+ *   console.log('Home preset:', data.homePreset)
+ * }
+ * ```
+ *
+ * @category PTZ
+ */
+export declare interface PtzSettings {
+    /** Array of saved preset positions */
+    presets: PtzPreset[];
+    /** Name of the home preset, or null if none is set */
+    homePreset: string | null;
+    /** Automation mode controlling automatic camera movement */
+    mode: PtzMode;
+    /** Seconds of inactivity before automatic movement begins */
+    autoStartDelay: number;
+}
+
+/**
+ * Parameters for updating PTZ settings (all fields optional).
+ *
+ * @remarks
+ * Used with `updatePtzSettings()` to partially update PTZ configuration.
+ * Only provided fields are updated; omitted fields retain their current values.
+ *
+ * @example
+ * ```typescript
+ * import { updatePtzSettings } from 'een-api-toolkit'
+ *
+ * // Change mode only
+ * await updatePtzSettings('camera-id', { mode: 'tour' })
+ *
+ * // Update presets and home preset
+ * await updatePtzSettings('camera-id', {
+ *   presets: [{ name: 'Entrance', position: { x: 0, y: 0, z: 1 }, timeAtPreset: 10 }],
+ *   homePreset: 'Entrance'
+ * })
+ * ```
+ *
+ * @category PTZ
+ */
+export declare interface PtzSettingsUpdate {
+    /** Updated array of preset positions */
+    presets?: PtzPreset[];
+    /** Updated home preset name */
+    homePreset?: string | null;
+    /** Updated automation mode */
+    mode?: PtzMode;
+    /** Updated auto-start delay in seconds */
+    autoStartDelay?: number;
+}
+
+/**
+ * Step size for directional movements.
+ *
+ * @category PTZ
+ */
+export declare type PtzStepSize = 'small' | 'medium' | 'large';
+
 /**
  * Result of getting a recorded image.
  *
@@ -6815,6 +7193,40 @@ export declare interface UpdateLayoutParams {
     panes?: LayoutPane[];
 }
 
+/**
+ * Update PTZ settings for a camera (partial update).
+ *
+ * @remarks
+ * Updates PTZ configuration via `PATCH /api/v3.0/cameras/{cameraId}/ptz/settings`.
+ * Only provided fields are updated; omitted fields retain their current values.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/updateptzsettings).
+ *
+ * @param cameraId - The unique identifier of the PTZ camera
+ * @param settings - The settings fields to update
+ * @returns A Result containing void on success or an error
+ *
+ * @example
+ * ```typescript
+ * import { updatePtzSettings } from 'een-api-toolkit'
+ *
+ * // Change mode to tour
+ * await updatePtzSettings('camera-123', { mode: 'tour' })
+ *
+ * // Add a preset and set it as home
+ * await updatePtzSettings('camera-123', {
+ *   presets: [
+ *     { name: 'Entrance', position: { x: 0, y: 0, z: 1 }, timeAtPreset: 10 }
+ *   ],
+ *   homePreset: 'Entrance'
+ * })
+ * ```
+ *
+ * @category PTZ
+ */
+export declare function updatePtzSettings(cameraId: string, settings: PtzSettingsUpdate): Promise<Result<void>>;
+
 /**
  * Pinia store for authentication state management
  */