een-api-toolkit 0.3.15 → 0.3.20

package/dist/index.d.ts

@@ -514,6 +514,187 @@ export declare interface CameraStreamUrls {
     jpeg?: string;
 }
 
+/**
+ * Connect to an SSE event subscription to receive real-time events.
+ *
+ * @remarks
+ * Opens an SSE connection to the provided URL and calls the `onEvent` callback
+ * for each event received. The connection automatically handles reconnection
+ * on errors.
+ *
+ * Note: SSE connections require authentication. The token is passed via the
+ * `Authorization` header. Since EventSource doesn't support custom headers,
+ * we use fetch with ReadableStream to implement SSE.
+ *
+ * @param sseUrl - The SSE URL from the event subscription's deliveryConfig
+ * @param options - Connection options including event and error callbacks
+ * @returns A Result containing the SSE connection handle or an error
+ *
+ * @example
+ * ```typescript
+ * import { createEventSubscription, connectToEventSubscription } from 'een-api-toolkit'
+ *
+ * // First create a subscription
+ * const { data: subscription } = await createEventSubscription({
+ *   deliveryConfig: { type: 'serverSentEvents.v1' },
+ *   filters: [{
+ *     actors: ['camera:100d4c41'],
+ *     types: [{ id: 'een.motionDetectionEvent.v1' }]
+ *   }]
+ * })
+ *
+ * if (subscription?.deliveryConfig.type === 'serverSentEvents.v1') {
+ *   // Connect to SSE stream
+ *   const { data: connection, error } = connectToEventSubscription(
+ *     subscription.deliveryConfig.sseUrl!,
+ *     {
+ *       onEvent: (event) => {
+ *         console.log(`Event: ${event.type} from ${event.actorId}`)
+ *       },
+ *       onError: (err) => {
+ *         console.error('SSE error:', err.message)
+ *       },
+ *       onStatusChange: (status) => {
+ *         console.log('Connection status:', status)
+ *       }
+ *     }
+ *   )
+ *
+ *   // Later, disconnect
+ *   if (connection) {
+ *     connection.close()
+ *   }
+ * }
+ * ```
+ *
+ * @category EventSubscriptions
+ */
+export declare function connectToEventSubscription(sseUrl: string, options: SSEConnectionOptions): Result<SSEConnection>;
+
+/**
+ * Create a new event subscription.
+ *
+ * @remarks
+ * Creates a new event subscription at `/api/v3.0/eventSubscriptions`.
+ * For SSE subscriptions, use `connectToEventSubscription()` with the returned
+ * `sseUrl` to start receiving events.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/createeventsubscription).
+ *
+ * @param params - Parameters for creating the subscription
+ * @returns A Result containing the created event subscription or an error
+ *
+ * @example
+ * ```typescript
+ * import { createEventSubscription, connectToEventSubscription } from 'een-api-toolkit'
+ *
+ * // Create an SSE subscription for motion events
+ * const { data, error } = await createEventSubscription({
+ *   deliveryConfig: { type: 'serverSentEvents.v1' },
+ *   filters: [{
+ *     actors: ['camera:100d4c41'],
+ *     types: [{ id: 'een.motionDetectionEvent.v1' }]
+ *   }]
+ * })
+ *
+ * if (data && data.deliveryConfig.type === 'serverSentEvents.v1') {
+ *   // Connect to the SSE stream
+ *   const { data: connection } = connectToEventSubscription(
+ *     data.deliveryConfig.sseUrl!,
+ *     { onEvent: (event) => console.log('Event:', event) }
+ *   )
+ * }
+ * ```
+ *
+ * @category EventSubscriptions
+ */
+export declare function createEventSubscription(params: CreateEventSubscriptionParams): Promise<Result<EventSubscription>>;
+
+/**
+ * Parameters for creating an event subscription.
+ *
+ * @remarks
+ * Creates a new subscription with the specified delivery type and filters.
+ * For SSE subscriptions, use `connectToEventSubscription()` to start receiving events.
+ *
+ * @example
+ * ```typescript
+ * import { createEventSubscription } from 'een-api-toolkit'
+ *
+ * // Create an SSE subscription for motion events from a camera
+ * const { data, error } = await createEventSubscription({
+ *   deliveryConfig: { type: 'serverSentEvents.v1' },
+ *   filters: [{
+ *     actors: ['camera:100d4c41'],
+ *     types: [{ id: 'een.motionDetectionEvent.v1' }]
+ *   }]
+ * })
+ *
+ * if (data) {
+ *   console.log(`Created subscription: ${data.id}`)
+ *   // For SSE subscriptions, connect to the sseUrl
+ *   if (data.deliveryConfig.type === 'serverSentEvents.v1') {
+ *     console.log(`SSE URL: ${data.deliveryConfig.sseUrl}`)
+ *   }
+ * }
+ * ```
+ *
+ * @category EventSubscriptions
+ */
+export declare interface CreateEventSubscriptionParams {
+    /** Delivery configuration */
+    deliveryConfig: DeliveryConfigCreate;
+    /** List of filters for the subscription */
+    filters: FilterCreate[];
+}
+
+/**
+ * Delete an event subscription.
+ *
+ * @remarks
+ * Deletes an event subscription at `/api/v3.0/eventSubscriptions/{id}`.
+ * Any active SSE connections to this subscription will be closed.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/deleteeventsubscription).
+ *
+ * @param subscriptionId - The unique identifier of the subscription to delete
+ * @returns A Result with void data on success or an error
+ *
+ * @example
+ * ```typescript
+ * import { deleteEventSubscription } from 'een-api-toolkit'
+ *
+ * const { error } = await deleteEventSubscription('f3d6f55d5ba546168758a309508f4419')
+ * if (error) {
+ *   console.error('Failed to delete:', error.message)
+ * } else {
+ *   console.log('Subscription deleted successfully')
+ * }
+ * ```
+ *
+ * @category EventSubscriptions
+ */
+export declare function deleteEventSubscription(subscriptionId: string): Promise<Result<void>>;
+
+/**
+ * Delivery configuration (union type).
+ *
+ * @remarks
+ * Describes how events will be delivered to the subscriber.
+ *
+ * @category EventSubscriptions
+ */
+export declare type DeliveryConfig = SSEDeliveryConfig | WebhookDeliveryConfig;
+
+/**
+ * Delivery configuration for creation (union type).
+ *
+ * @category EventSubscriptions
+ */
+export declare type DeliveryConfigCreate = SSEDeliveryConfigCreate | WebhookDeliveryConfigCreate;
+
 /**
  * Error object returned when an operation fails.
  *
@@ -738,6 +919,99 @@ export declare interface EventMetric {
     [key: string]: unknown;
 }
 
+/**
+ * Event subscription entity from EEN API v3.0.
+ *
+ * @remarks
+ * Represents an event subscription in the Eagle Eye Networks platform.
+ * Subscriptions allow receiving real-time events via SSE or webhooks.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/listeventsubscriptions).
+ *
+ * @example
+ * ```typescript
+ * import { listEventSubscriptions, type EventSubscription } from 'een-api-toolkit'
+ *
+ * const { data, error } = await listEventSubscriptions()
+ * if (data) {
+ *   data.results.forEach((sub: EventSubscription) => {
+ *     console.log(`Subscription ${sub.id}: ${sub.deliveryConfig.type}`)
+ *     if (sub.deliveryConfig.type === 'serverSentEvents.v1') {
+ *       console.log(`  SSE URL: ${sub.deliveryConfig.sseUrl}`)
+ *     }
+ *   })
+ * }
+ * ```
+ *
+ * @category EventSubscriptions
+ */
+export declare interface EventSubscription {
+    /** Unique identifier for the subscription */
+    id: string;
+    /** Subscription configuration (lifecycle, TTL) */
+    subscriptionConfig?: EventSubscriptionConfig;
+    /** Delivery configuration (SSE or webhook) */
+    deliveryConfig: DeliveryConfig;
+}
+
+/**
+ * Event subscription configuration.
+ *
+ * @remarks
+ * Contains lifecycle and TTL settings for the subscription.
+ * This is read-only and set by the server based on delivery type.
+ *
+ * @category EventSubscriptions
+ */
+export declare interface EventSubscriptionConfig {
+    /** Subscription lifecycle type */
+    lifeCycle: EventSubscriptionLifecycle;
+    /** Time-to-live in seconds for temporary subscriptions */
+    timeToLiveSeconds?: number;
+}
+
+/**
+ * Delivery type for event subscriptions.
+ *
+ * @remarks
+ * - `serverSentEvents.v1`: Connect via SSE to receive events in real-time
+ * - `webhook.v1`: Events are pushed to a client-provided URL
+ *
+ * @category EventSubscriptions
+ */
+export declare type EventSubscriptionDeliveryType = 'serverSentEvents.v1' | 'webhook.v1';
+
+/**
+ * Filter for event subscriptions.
+ *
+ * @remarks
+ * A filter defines which events will be delivered. Events must match
+ * all conditions within a filter to be delivered. The subscription
+ * receives events matching any of its filters.
+ *
+ * @category EventSubscriptions
+ */
+export declare interface EventSubscriptionFilter {
+    /** Unique filter ID within the subscription */
+    id: string;
+    /** List of actors to filter (format: "type:id", e.g., "camera:100d4c41") */
+    actors: string[];
+    /** List of event types to filter */
+    types: EventTypeFilter[];
+}
+
+/**
+ * Subscription lifecycle type.
+ *
+ * @remarks
+ * - `temporary`: Removed when deleted or when no client uses it for timeToLiveSeconds
+ * - `persistent`: Remains active indefinitely until explicitly deleted
+ *
+ * @category EventSubscriptions
+ */
+export declare type EventSubscriptionLifecycle = 'temporary' | 'persistent';
+
 /**
  * Event type definition from EEN API v3.0.
  *
@@ -756,6 +1030,27 @@ export declare interface EventType {
     description: string;
 }
 
+/**
+ * Event type filter for subscriptions.
+ *
+ * @remarks
+ * Specifies which event types should trigger the subscription.
+ * Use `listEventTypes()` to get available event type IDs.
+ *
+ * @example
+ * ```typescript
+ * const typeFilter: EventTypeFilter = {
+ *   id: 'een.motionDetectionEvent.v1'
+ * }
+ * ```
+ *
+ * @category EventSubscriptions
+ */
+export declare interface EventTypeFilter {
+    /** Event type identifier (e.g., "een.motionDetectionEvent.v1") */
+    id: string;
+}
+
 /* Excluded from this release type: failure */
 
 /**
@@ -868,6 +1163,53 @@ export declare type FeedMediaType = 'video' | 'audio' | 'image' | 'halfDuplex' |
  */
 export declare type FeedStreamType = 'main' | 'preview' | 'talkdown';
 
+/**
+ * Filter creation parameters.
+ *
+ * @remarks
+ * Used when creating filters inline with a subscription.
+ *
+ * @example
+ * ```typescript
+ * const filter: FilterCreate = {
+ *   actors: ['camera:100d4c41'],
+ *   types: [{ id: 'een.motionDetectionEvent.v1' }]
+ * }
+ * ```
+ *
+ * @category EventSubscriptions
+ */
+export declare interface FilterCreate {
+    /** List of actors to filter (format: "type:id", e.g., "camera:100d4c41") */
+    actors: string[];
+    /** List of event types to filter */
+    types: EventTypeFilter[];
+}
+
+/**
+ * Convert ISO 8601 timestamp from Z format to +00:00 format.
+ *
+ * @remarks
+ * The EEN API requires timestamps in +00:00 format, not Z format.
+ * This function converts timestamps like `2024-01-01T00:00:00.000Z`
+ * to `2024-01-01T00:00:00.000+00:00`.
+ *
+ * @param timestamp - ISO 8601 timestamp string
+ * @returns Timestamp in +00:00 format
+ *
+ * @example
+ * ```typescript
+ * formatTimestamp('2024-01-01T00:00:00.000Z')
+ * // Returns: '2024-01-01T00:00:00.000+00:00'
+ *
+ * formatTimestamp(new Date().toISOString())
+ * // Returns: timestamp with +00:00 suffix
+ * ```
+ *
+ * @category Utilities
+ */
+export declare function formatTimestamp(timestamp: string): string;
+
 /**
  * Exchange authorization code for access token
  */
@@ -1361,6 +1703,35 @@ export declare interface GetEventParams {
     include?: string[];
 }
 
+/**
+ * Get a specific event subscription by ID.
+ *
+ * @remarks
+ * Fetches a single event subscription from `/api/v3.0/eventSubscriptions/{id}`.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/geteventsubscription).
+ *
+ * @param subscriptionId - The unique identifier of the subscription to fetch
+ * @returns A Result containing the event subscription or an error
+ *
+ * @example
+ * ```typescript
+ * import { getEventSubscription } from 'een-api-toolkit'
+ *
+ * const { data, error } = await getEventSubscription('f3d6f55d5ba546168758a309508f4419')
+ * if (data) {
+ *   console.log(`Subscription: ${data.id}`)
+ *   if (data.deliveryConfig.type === 'serverSentEvents.v1') {
+ *     console.log(`SSE URL: ${data.deliveryConfig.sseUrl}`)
+ *   }
+ * }
+ * ```
+ *
+ * @category EventSubscriptions
+ */
+export declare function getEventSubscription(subscriptionId: string): Promise<Result<EventSubscription>>;
+
 /**
  * Get a live image from a camera.
  *
@@ -2343,6 +2714,66 @@ export declare interface ListEventsParams {
     include?: string[];
 }
 
+/**
+ * List all event subscriptions for the current account.
+ *
+ * @remarks
+ * Fetches a paginated list of event subscriptions from `/api/v3.0/eventSubscriptions`.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/listeventsubscriptions).
+ *
+ * @param params - Optional pagination parameters
+ * @returns A Result containing a paginated list of event subscriptions or an error
+ *
+ * @example
+ * ```typescript
+ * import { listEventSubscriptions } from 'een-api-toolkit'
+ *
+ * const { data, error } = await listEventSubscriptions()
+ * if (data) {
+ *   console.log(`Found ${data.results.length} subscriptions`)
+ *   data.results.forEach(sub => {
+ *     console.log(`${sub.id}: ${sub.deliveryConfig.type}`)
+ *   })
+ * }
+ * ```
+ *
+ * @category EventSubscriptions
+ */
+export declare function listEventSubscriptions(params?: ListEventSubscriptionsParams): Promise<Result<PaginatedResult<EventSubscription>>>;
+
+/**
+ * Parameters for listing event subscriptions.
+ *
+ * @remarks
+ * Supports pagination via pageSize and pageToken.
+ *
+ * @example
+ * ```typescript
+ * import { listEventSubscriptions } from 'een-api-toolkit'
+ *
+ * // Get first page
+ * const { data } = await listEventSubscriptions({ pageSize: 10 })
+ *
+ * // Get next page
+ * if (data?.nextPageToken) {
+ *   const { data: page2 } = await listEventSubscriptions({
+ *     pageSize: 10,
+ *     pageToken: data.nextPageToken
+ *   })
+ * }
+ * ```
+ *
+ * @category EventSubscriptions
+ */
+export declare interface ListEventSubscriptionsParams {
+    /** Number of results per page */
+    pageSize?: number;
+    /** Token for fetching a specific page */
+    pageToken?: string;
+}
+
 /**
  * List all available event types.
  *
@@ -3114,6 +3545,125 @@ export declare type Result<T> = {
  */
 export declare function revokeToken(): Promise<Result<void>>;
 
+/**
+ * SSE connection handle.
+ *
+ * @remarks
+ * Returned by `connectToEventSubscription()`. Use `close()` to disconnect
+ * and `status` to check the current connection state.
+ *
+ * @example
+ * ```typescript
+ * const { data: connection } = connectToEventSubscription(sseUrl, {
+ *   onEvent: (event) => console.log('Event:', event),
+ *   onStatusChange: (status) => console.log('Status:', status)
+ * })
+ *
+ * // Later, disconnect
+ * if (connection) {
+ *   connection.close()
+ * }
+ * ```
+ *
+ * @category EventSubscriptions
+ */
+export declare interface SSEConnection {
+    /** Close the SSE connection */
+    close: () => void;
+    /** Current connection status */
+    status: SSEConnectionStatus;
+}
+
+/**
+ * Options for connecting to an SSE event subscription.
+ *
+ * @category EventSubscriptions
+ */
+export declare interface SSEConnectionOptions {
+    /** Callback when an event is received */
+    onEvent: (event: SSEEvent) => void;
+    /** Callback when an error occurs */
+    onError?: (error: Error) => void;
+    /** Callback when connection status changes */
+    onStatusChange?: (status: SSEConnectionStatus) => void;
+}
+
+/**
+ * SSE connection status.
+ *
+ * @category EventSubscriptions
+ */
+export declare type SSEConnectionStatus = 'connecting' | 'connected' | 'disconnected' | 'error';
+
+/**
+ * SSE delivery configuration.
+ *
+ * @remarks
+ * Configuration for Server-Sent Events delivery type.
+ * The `sseUrl` is provided by the server after subscription creation.
+ *
+ * @category EventSubscriptions
+ */
+export declare interface SSEDeliveryConfig {
+    /** Delivery type identifier */
+    type: 'serverSentEvents.v1';
+    /** URL to connect for receiving SSE events (read-only, provided by server) */
+    sseUrl?: string;
+}
+
+/**
+ * SSE delivery configuration for creation.
+ *
+ * @remarks
+ * Used when creating a subscription with SSE delivery.
+ *
+ * @category EventSubscriptions
+ */
+export declare interface SSEDeliveryConfigCreate {
+    /** Delivery type identifier */
+    type: 'serverSentEvents.v1';
+}
+
+/**
+ * Event received via SSE.
+ *
+ * @remarks
+ * This is the event payload delivered through the SSE connection.
+ * The structure matches the Event type from the events API.
+ *
+ * @category EventSubscriptions
+ */
+export declare interface SSEEvent {
+    /** Unique identifier for the event */
+    id: string;
+    /** ISO 8601 timestamp when the event started */
+    startTimestamp: string;
+    /** ISO 8601 timestamp when the event ended (null for point-in-time events) */
+    endTimestamp?: string | null;
+    /** Whether this is a span event (has duration) or point-in-time event */
+    span?: boolean;
+    /** ID of the account this event belongs to */
+    accountId?: string;
+    /** ID of the actor (device/entity) that generated the event */
+    actorId: string;
+    /** Account ID of the actor */
+    actorAccountId?: string;
+    /** Type of actor that generated the event */
+    actorType?: string;
+    /** ID of the entity that created the event */
+    creatorId?: string;
+    /** Event type identifier (e.g., "een.motionDetectionEvent.v1") */
+    type: string;
+    /** List of data schema types included in this event */
+    dataSchemas?: string[];
+    /** Event data objects (varies by event type) */
+    data?: Array<{
+        type: string;
+        creatorId?: string;
+        [key: string]: unknown;
+    }>;
+}
+
 /**
  * Human-readable descriptions for each storage strategy.
  * Useful for displaying storage information in UI components.
@@ -3376,4 +3926,39 @@ export declare interface UserProfile {
     language?: string;
 }
 
+/**
+ * Webhook delivery configuration.
+ *
+ * @remarks
+ * Configuration for webhook delivery type.
+ * The `secret` is provided by the server for signature verification.
+ *
+ * @category EventSubscriptions
+ */
+export declare interface WebhookDeliveryConfig {
+    /** Delivery type identifier */
+    type: 'webhook.v1';
+    /** Base64 encoded secret for signature verification (read-only) */
+    secret?: string;
+}
+
+/**
+ * Webhook delivery configuration for creation.
+ *
+ * @remarks
+ * Used when creating a subscription with webhook delivery.
+ *
+ * @category EventSubscriptions
+ */
+export declare interface WebhookDeliveryConfigCreate {
+    /** Delivery type identifier */
+    type: 'webhook.v1';
+    /** HTTPS URL where webhook events will be sent */
+    webhookUrl: string;
+    /** Email address of technical contact */
+    technicalContactEmail: string;
+    /** Name of technical contact */
+    technicalContactName: string;
+}
+
 export { }