feat(client): implement open_canvas method for workspace operations

Docs/Workspaces_API.md

@@ -1,4 +1,3 @@
-```markdown
 ## Workspaces API
 
 The workspaces API operates on the workspaces on a client.
@@ -185,4 +184,39 @@ curl -X PATCH -H "Private-Token: <access token>" -d '{"pinned":"false"}' https:/
   "workspace_name": "Workspace 1",
   "workspace_state": "open"
 }
-```
+```
+
+### Open Canvas in Workspace
+
+Opens a canvas in a workspace. This is the correct way to open a canvas, not PATCH.
+
+```bash
+POST /clients/:client_id/workspaces/:workspace_index/open-canvas
+```
+
+| Attribute         | Type   | Required | Description                |
+|------------------|--------|----------|----------------------------|
+| client_id (path)  | uuid   | yes      | ID of the client           |
+| workspace_index   | int    | yes      | Index of the workspace     |
+| canvas_id (body)  | uuid   | yes      | ID of the canvas to open   |
+| server_id (body)  | uuid   | yes      | Server ID for the workspace|
+
+**Example cURL Request**:
+```bash
+curl -X POST -H "Private-Token: <access token>" \
+  -d '{"canvas_id": "abc123", "server_id": "srv456"}' \
+  https://canvus.example.com/api/v1/clients/e5cad8d4-7051-4051-97bc-13e41fd81ca7/workspaces/0/open-canvas
+```
+
+**Example SDK Usage**:
+```python
+await client.open_canvas(
+    client_id="abc123",
+    workspace_index=0,
+    canvas_id="canvas-xyz",
+    server_id="server-xyz"
+)
+```
+
+**Response**:
+Returns a dictionary with the result of the operation.

canvus_api/client.py

@@ -2947,3 +2947,44 @@ async def subscribe_note(
         finally:
             # Ensure response is closed
             await response.release()
+
+    async def open_canvas(
+        self,
+        client_id: str,
+        workspace_index: int,
+        canvas_id: str,
+        server_id: str,
+    ) -> Dict[str, Any]:
+        """Open a canvas in a workspace.
+
+        Args:
+            client_id (str): The client ID.
+            workspace_index (int): The workspace index.
+            canvas_id (str): The canvas ID to open.
+            server_id (str): The server ID for the workspace.
+
+        Returns:
+            Dict[str, Any]: The response from the API.
+
+        Raises:
+            ValidationError: If required parameters are missing or invalid.
+            AuthenticationError: If authentication fails.
+            CanvusAPIError: For other API-related errors.
+
+        Example:
+            >>> await client.open_canvas(
+            ...     client_id="abc123",
+            ...     workspace_index=0,
+            ...     canvas_id="canvas-xyz",
+            ...     server_id="server-xyz"
+            ... )
+        """
+        if not client_id or not isinstance(workspace_index, int) or not canvas_id or not server_id:
+            raise ValidationError("All parameters are required and must be valid.")
+        endpoint = f"clients/{client_id}/workspaces/{workspace_index}/open-canvas"
+        payload = {"canvas_id": canvas_id, "server_id": server_id}
+        return await self._request(
+            "POST",
+            endpoint,
+            json_data=payload,
+        )

tests/test_client_operations.py

@@ -308,6 +308,39 @@ async def test_workspace_operations(client: CanvusClient) -> None:
         raise
 
 
+@pytest.mark.asyncio
+async def test_open_canvas_method(client: CanvusClient):
+    """Test the open_canvas method of CanvusClient."""
+    print_header("Testing open_canvas method")
+
+    # Discover client and workspace
+    client_id = await test_client_discovery(client)
+    workspaces = await client.get_client_workspaces(client_id)
+    if not workspaces:
+        print_error("No workspaces found to test with")
+        return
+    workspace = workspaces[0]
+
+    # Create a test canvas
+    test_canvas_name = f"OpenCanvas Test {time.time()}"
+    test_canvas = await client.create_canvas({"name": test_canvas_name, "width": 1920, "height": 1080})
+    print_success(f"Created test canvas: {test_canvas.id}")
+
+    # Use open_canvas method
+    response = await client.open_canvas(
+        client_id=client_id,
+        workspace_index=workspace.index,
+        canvas_id=test_canvas.id,
+        server_id=workspace.server_id,
+    )
+    print_info(f"open_canvas response: {response}")
+
+    # Wait for workspace to update
+    opened = await wait_for_workspace_canvas(client, client_id, workspace.index, test_canvas.id)
+    assert opened, "Workspace did not open the test canvas via open_canvas method"
+    print_success("open_canvas method worked as expected")
+
+
 async def main():
     """Main test function."""
     print_header("Starting Client Operations Tests")