add archive methods and tests

Author: maxkahan

video/src/vonage_video/errors.py

@@ -31,3 +31,7 @@ class LayoutStylesheetError(VideoError):
 
 class LayoutScreenshareTypeError(VideoError):
     """Error with the `screenshare_type` property when setting a layout."""
+
+
+class InvalidArchiveStateError(VideoError):
+    """The archive state was invalid for the specified operation."""

video/src/vonage_video/models/archive.py

@@ -26,7 +26,7 @@ class ListArchivesFilter(BaseModel):
     """
 
     offset: Optional[int] = None
-    page_size: Optional[int] = Field(1000, serialization_alias='count')
+    page_size: Optional[int] = Field(100, serialization_alias='count')
     session_id: Optional[str] = None
 
 
@@ -44,54 +44,81 @@ class ArchiveStream(BaseModel):
     has_video: Optional[bool] = Field(None, validation_alias='hasVideo')
 
 
+class Transcription(BaseModel):
+    """Model for transcription options for an archive.
+
+    Args:
+        status (str, Optional): The status of the transcription.
+        reason (str, Optional): May give a brief reason for the transcription status.
+    """
+
+    status: Optional[str] = None
+    reason: Optional[str] = None
+
+
 class Archive(BaseModel):
     """Model for an archive.
 
     Args:
+        id (str, Optional): The unique archive ID.
+        status (ArchiveStatus, Optional): The status of the archive.
+        name (str, Optional): The name of the archive.
+        reason (str, Optional): May give a brief reason for the archive status.
+        session_id (str, Optional): The session ID of the Vonage Video session.
+        application_id (str, Optional): The Vonage application ID.
         created_at (int, Optional): The timestamp when the archive when the archive
             started recording, expressed in milliseconds since the Unix epoch.
+        size (int, Optional): The size of the archive.
         duration (int, Optional): The duration of the archive in seconds.
             For archives that have are being recorded, this value is set to 0.
+        output_mode (OutputMode, Optional): The output mode of the archive.
+        stream_mode (StreamMode, Optional): Whether streams included in the archive
+            are selected automatically (`auto`, the default) or manually (`manual`).
         has_audio (bool, Optional): Whether the archive will record audio.
         has_video (bool, Optional): Whether the archive will record video.
-        id (str, Optional): The unique archive ID.
+        has_transcription (bool, Optional): Whether audio will be transcribed.
+        sha256_sum (str, Optional): The SHA-256 hash of the archive.
+        password (str, Optional): The password for the archive.
+        updated_at (int, Optional): The timestamp when the archive was last updated,
+            expressed in milliseconds since the Unix epoch.
         multi_archive_tag (str, Optional): Set this to support recording multiple
             archives for the same session simultaneously. Set this to a unique string
             for each simultaneous archive of an ongoing session.
-        name (str, Optional): The name of the archive.
-        application_id (str, Optional): The Vonage application ID.
-        reason (str, Optional): This is set when the `status` is `stopped` or `failed`.
+        event (str, Optional): The event that triggered the response.
         resolution (VideoResolution, Optional): The resolution of the archive.
-        session_id (str, Optional): The session ID of the Vonage Video session.
-        size (int, Optional): The size of the archive.
-        status (ArchiveStatus, Optional): The status of the archive.
-        stream_mode (StreamMode, Optional): Whether streams included in the archive
-            are selected automatically (`auto`, the default) or manually (`manual`).
         streams (List[ArchiveStream], Optional): The streams in the archive.
         url (str, Optional): The download URL of the available archive file.
             This is only set for an archive with the status set to `available`.
+        transcription (Transcription, Optional): Transcription options for the archive.
     """
 
-    created_at: Optional[int] = Field(None, validation_alias='createdAt')
-    duration: Optional[int] = None
-    has_audio: Optional[bool] = Field(None, validation_alias='hasAudio')
-    has_video: Optional[bool] = Field(None, validation_alias='hasVideo')
     id: Optional[str] = None
-    multi_archive_tag: Optional[str] = Field(None, validation_alias='multiArchiveTag')
+    status: Optional[ArchiveStatus] = None
     name: Optional[str] = None
-    application_id: Optional[str] = Field(None, validation_alias='applicationId')
     reason: Optional[str] = None
-    resolution: Optional[VideoResolution] = None
     session_id: Optional[str] = Field(None, validation_alias='sessionId')
+    application_id: Optional[str] = Field(None, validation_alias='applicationId')
+    created_at: Optional[int] = Field(None, validation_alias='createdAt')
     size: Optional[int] = None
-    status: Optional[ArchiveStatus] = None
+    duration: Optional[int] = None
+    output_mode: Optional[OutputMode] = Field(None, validation_alias='outputMode')
     stream_mode: Optional[StreamMode] = Field(None, validation_alias='streamMode')
+    has_audio: Optional[bool] = Field(None, validation_alias='hasAudio')
+    has_video: Optional[bool] = Field(None, validation_alias='hasVideo')
+    has_transcription: Optional[bool] = Field(None, validation_alias='hasTranscription')
+    sha256_sum: Optional[str] = Field(None, validation_alias='sha256sum')
+    password: Optional[str] = None
+    updated_at: Optional[int] = Field(None, validation_alias='updatedAt')
+    multi_archive_tag: Optional[str] = Field(None, validation_alias='multiArchiveTag')
+    event: Optional[str] = None
+    resolution: Optional[VideoResolution] = None
     streams: Optional[List[ArchiveStream]] = None
     url: Optional[str] = None
+    transcription: Optional[Transcription] = None
 
 
-class Layout(BaseModel):
-    """Model for layout options for an archive.
+class ComposedLayout(BaseModel):
+    """Model for layout options for a composed archive.
 
     Args:
         type (str): Specify this to assign the initial layout type for the archive.
@@ -154,7 +181,10 @@ class CreateArchiveRequest(BaseModel):
     session_id: str = Field(..., serialization_alias='sessionId')
     has_audio: Optional[bool] = Field(None, serialization_alias='hasAudio')
     has_video: Optional[bool] = Field(None, serialization_alias='hasVideo')
-    layout: Optional[Layout] = None
+    has_transcription: Optional[bool] = Field(
+        None, serialization_alias='hasTranscription'
+    )
+    layout: Optional[ComposedLayout] = None
     multi_archive_tag: Optional[str] = Field(None, serialization_alias='multiArchiveTag')
     name: Optional[str] = None
     output_mode: Optional[OutputMode] = Field(None, serialization_alias='outputMode')
@@ -180,3 +210,25 @@ def no_layout_or_resolution_for_individual_archives(self):
                 'The `layout` property cannot be set for `archive_mode: \'individual\'`.'
             )
         return self
+
+    @model_validator(mode='after')
+    def transcription_only_for_individual_archives(self):
+        if self.output_mode == OutputMode.COMPOSED and self.has_transcription is True:
+            raise IndividualArchivePropertyError(
+                'The `has_transcription` property can only be set for `archive_mode: \'individual\'`.'
+            )
+        return self
+
+
+class AddStreamRequest(BaseModel):
+    """Model for adding a stream to an archive.
+
+    Args:
+        stream_id (str): ID of the stream to add to the archive.
+        has_audio (bool, Optional): Whether the stream has audio.
+        has_video (bool, Optional): Whether the stream has video.
+    """
+
+    stream_id: str = Field(..., serialization_alias='addStream')
+    has_audio: Optional[bool] = Field(None, serialization_alias='hasAudio')
+    has_video: Optional[bool] = Field(None, serialization_alias='hasVideo')

video/src/vonage_video/models/enums.py

@@ -86,3 +86,4 @@ class ArchiveStatus(str, Enum):
     STARTED = 'started'
     STOPPED = 'stopped'
     UPLOADED = 'uploaded'
+    DELETED = 'deleted'

video/src/vonage_video/models/experience_composer.py

@@ -78,4 +78,4 @@ class ListExperienceComposersFilter(BaseModel):
     """
 
     offset: Optional[int] = None
-    page_size: Optional[int] = Field(1000, serialization_alias='count')
+    page_size: Optional[int] = Field(100, serialization_alias='count')

video/src/vonage_video/video.py

@@ -1,8 +1,16 @@
 from typing import List, Optional, Tuple
 
 from pydantic import validate_call
+from vonage_http_client.errors import HttpRequestError
 from vonage_http_client.http_client import HttpClient
-from vonage_video.models.archive import Archive, CreateArchiveRequest, ListArchivesFilter
+from vonage_video.errors import InvalidArchiveStateError
+from vonage_video.models.archive import (
+    AddStreamRequest,
+    Archive,
+    ComposedLayout,
+    CreateArchiveRequest,
+    ListArchivesFilter,
+)
 from vonage_video.models.audio_connector import AudioConnectorData, AudioConnectorOptions
 from vonage_video.models.captions import CaptionsData, CaptionsOptions
 from vonage_video.models.experience_composer import (
@@ -296,7 +304,7 @@ def list_experience_composers(
                 composer objects, the total count of Experience Composers and the required offset value
                 for the next page, if applicable.
                 i.e.
-                experience_composers: List[ExperienceComposer], count: int, next_page_index: Optional[int]
+                experience_composers: List[ExperienceComposer], count: int, next_page_offset: Optional[int]
         """
         response = self._http_client.get(
             self._http_client.video_host,
@@ -352,8 +360,165 @@ def stop_experience_composer(self, experience_composer_id: str) -> None:
     def list_archives(
         self, filter: ListArchivesFilter
     ) -> Tuple[List[Archive], int, Optional[int]]:
-        pass
+        """Lists archives associated with a Vonage Application.
+
+        Args:
+            filter (ListArchivesFilter): The filters for the archives.
+
+        Returns:
+            Tuple[List[Archive], int, Optional[int]]: A tuple containing a list of archive objects,
+                the total count of archives and the required offset value for the next page, if applicable.
+                i.e.
+                archives: List[Archive], count: int, next_page_offset: Optional[int]
+        """
+        response = self._http_client.get(
+            self._http_client.video_host,
+            f'/v2/project/{self._http_client.auth.application_id}/archive',
+            filter.model_dump(exclude_none=True, by_alias=True),
+        )
+
+        index = filter.offset + 1 or 1
+        page_size = filter.page_size
+        archives = []
+
+        try:
+            for archive in response['items']:
+                archives.append(Archive(**archive))
+        except KeyError:
+            return [], 0, None
+
+        count = response['count']
+        if count > page_size * (index):
+            return archives, count, index
+        return archives, count, None
 
     @validate_call
-    def create_archive(self, options: CreateArchiveRequest) -> Archive:
-        pass
+    def start_archive(self, options: CreateArchiveRequest) -> Archive:
+        """Starts an archive in a Vonage Video API session.
+
+        Args:
+            options (CreateArchiveRequest): The options for the archive.
+
+        Returns:
+            Archive: The archive object.
+        """
+        response = self._http_client.post(
+            self._http_client.video_host,
+            f'/v2/project/{self._http_client.auth.application_id}/archive',
+            options.model_dump(exclude_none=True, by_alias=True),
+        )
+
+        return Archive(**response)
+
+    @validate_call
+    def get_archive(self, archive_id: str) -> Archive:
+        """Gets an archive from the Vonage Video API.
+
+        Args:
+            archive_id (str): The archive ID.
+
+        Returns:
+            Archive: The archive object.
+        """
+        response = self._http_client.get(
+            self._http_client.video_host,
+            f'/v2/project/{self._http_client.auth.application_id}/archive/{archive_id}',
+        )
+
+        return Archive(**response)
+
+    @validate_call
+    def delete_archive(self, archive_id: str) -> None:
+        """Deletes an archive from the Vonage Video API.
+
+        Args:
+            archive_id (str): The archive ID.
+
+        Raises:
+            InvalidArchiveStateError: If the archive has a status other than `available`, `uploaded`, or `deleted`.
+        """
+        try:
+            self._http_client.delete(
+                self._http_client.video_host,
+                f'/v2/project/{self._http_client.auth.application_id}/archive/{archive_id}',
+            )
+        except HttpRequestError as e:
+            if e.response.status_code == 409:
+                raise InvalidArchiveStateError(
+                    'You can only delete an archive that has one of the following statuses: `available` OR `uploaded` OR `deleted`.'
+                )
+            raise e
+
+    @validate_call
+    def add_stream_to_archive(self, archive_id: str, params: AddStreamRequest) -> None:
+        """Adds a stream to an archive in the Vonage Video API. Use this method to change the
+        streams included in a composed archive that was started with the streamMode set to "manual".
+
+        Args:
+            archive_id (str): The archive ID.
+            params (AddStreamRequest): Params for adding a stream to an archive.
+        """
+        self._http_client.patch(
+            self._http_client.video_host,
+            f'/v2/project/{self._http_client.auth.application_id}/archive/{archive_id}/streams',
+            params.model_dump(exclude_none=True, by_alias=True),
+        )
+
+    @validate_call
+    def remove_stream_from_archive(self, archive_id: str, stream_id: str) -> None:
+        """Removes a stream from an archive in the Vonage Video API.
+
+        Args:
+            archive_id (str): The archive ID.
+            stream_id (str): ID of the stream to remove.
+        """
+        self._http_client.patch(
+            self._http_client.video_host,
+            f'/v2/project/{self._http_client.auth.application_id}/archive/{archive_id}/streams',
+            params={'removeStream': stream_id},
+        )
+
+    @validate_call
+    def stop_archive(self, archive_id: str) -> Archive:
+        """Stops a Vonage Video API archive.
+
+        Args:
+            archive_id (str): The archive ID.
+
+        Returns:
+            Archive: The archive object.
+
+        Raises:
+            InvalidArchiveStateError: If the archive is not being recorded.
+        """
+        try:
+            response = self._http_client.post(
+                self._http_client.video_host,
+                f'/v2/project/{self._http_client.auth.application_id}/archive/{archive_id}/stop',
+            )
+        except HttpRequestError as e:
+            if e.response.status_code == 409:
+                raise InvalidArchiveStateError(
+                    'You can only stop an archive that is being recorded.'
+                )
+            raise e
+        return Archive(**response)
+
+    @validate_call
+    def change_archive_layout(self, archive_id: str, layout: ComposedLayout) -> Archive:
+        """Changes the layout of an archive in the Vonage Video API.
+
+        Args:
+            archive_id (str): The archive ID.
+            layout (ComposedLayout): The layout to change to.
+
+        Returns:
+            Archive: The archive object.
+        """
+        response = self._http_client.put(
+            self._http_client.video_host,
+            f'/v2/project/{self._http_client.auth.application_id}/archive/{archive_id}/layout',
+            layout.model_dump(exclude_none=True, by_alias=True),
+        )
+
+        return Archive(**response)

video/tests/data/archive.json

@@ -0,0 +1,23 @@
+{
+    "id": "5b1521e6-115f-4efd-bed9-e527b87f0699",
+    "status": "started",
+    "name": "first archive test",
+    "reason": "",
+    "sessionId": "test_session_id",
+    "applicationId": "test_application_id",
+    "createdAt": 1727870434974,
+    "size": 0,
+    "duration": 0,
+    "outputMode": "composed",
+    "streamMode": "manual",
+    "hasAudio": true,
+    "hasVideo": true,
+    "hasTranscription": false,
+    "sha256sum": "",
+    "password": "",
+    "updatedAt": 1727870434977,
+    "multiArchiveTag": "my-multi-archive",
+    "event": "archive",
+    "resolution": "1280x720",
+    "url": null
+}

video/tests/data/delete_archive_error.json

@@ -0,0 +1,5 @@
+{
+    "code": 15004,
+    "message": "You can only delete an archive that has one of the following statuses: available OR uploaded OR deleted",
+    "description": "You can only delete an archive that has one of the following statuses: available OR uploaded OR deleted"
+}