intuned-runtime 1.0.0__py3-none-any.whl → 1.1.1__py3-none-any.whl

intuned_cli/constants/readme.py

@@ -0,0 +1,134 @@
+readme = r"""# Intuned CLI
+
+## Development Commands
+
+For each command, add `--help` to see more details and options.
+
+### Initialize a Project
+`pipx run --spec intuned-runtime intuned init`
+
+Once you install the dependencies, you will have `intuned` command available in your environment.
+
+### Run an API
+`intuned run api <api-name> <parameters>`
+
+
+### Deploy a Project
+`intuned deploy [project-name]`
+
+
+
+### Create an auth session
+`intuned run authsession create <parameters>`
+
+
+
+### Validate an auth session
+`intuned run authsession validate <auth-session-name>`
+
+## Configuration
+
+### Environment Variables and Settings
+- `workspaceId`: Your Intuned workspace ID ([How to get your workspaceId](https://docs.intunedhq.com/docs/guides/platform/how-to-get-a-workspace-id))
+  - Set in `intuned.json` file under the `workspaceId` property
+  - Or provide via CLI with `--workspace-id` flag during deployment
+
+- `projectName`: The name of your Intuned project
+  - Set in `intuned.json` file under the `projectName` property
+  - Or override via command line when deploying with `yarn intuned deploy my-project-name` or `npm run intuned deploy my-project-name`
+
+- `INTUNED_API_KEY`: Your Intuned API key
+  - Set as an environment variable: `export INTUNED_API_KEY=your_api_key_here`
+  - Or include in your .env file for development
+  - Or provide via CLI with `--api-key` flag during deployment
+
+## Project Structure
+
+### Generated Artifacts
+- `./intuned.json`: Project configuration file
+- `./api`: Folder containing API implementation files
+- `./auth-sessions`: Folder containing auth-session APIs if you use them
+- `./auth-sessions-instances`: Folder containing auth session instances
+
+## Types of auth sessions
+- `MANUAL`: Manual auth session, records the session using a recorder and stores it in the `auth-sessions-instances` folder
+- `API`: Auth session created via create API, stores the session in the `auth-sessions-instances` folder
+
+### Notes
+- All commands should be run from the project root directory
+- Verify you're in the correct location by confirming the presence of package.json and intuned.json
+- Running commands from subdirectories may result in errors
+- You can manage your deployed projects through the Intuned platform
+
+## `Intuned.json` Reference
+```jsonc
+{
+  // Your Intuned workspace ID.
+  // Optional - If not provided here, it must be supplied via the \`--workspace-id\` flag during deployment.
+  "workspaceId": "your_workspace_id",
+
+  // The name of your Intuned project.
+  // Optional - If not provided here, it must be supplied via the command line when deploying.
+  "projectName": "your_project_name",
+
+  // Replication settings
+  "replication": {
+    // The maximum number of concurrent executions allowed via Intuned API. This does not affect jobs.
+    // A number of machines equal to this will be allocated to handle API requests.
+    // Not applicable if api access is disabled.
+    "maxConcurrentRequests": 1,
+
+    // The machine size to use for this project. This is applicable for both API requests and jobs.
+    // "standard": Standard machine size (6 shared vCPUs, 2GB RAM)
+    // "large": Large machine size (8 shared vCPUs, 4GB RAM)
+    // "xlarge": Extra large machine size (1 performance vCPU, 8GB RAM)
+    "size": "standard"
+  }
+
+  // Auth session settings
+  "authSessions": {
+    // Whether auth sessions are enabled for this project.
+    // If enabled, "auth-sessions/check.py" API must be implemented to validate the auth session.
+    "enabled": true,
+
+    // Whether to save Playwright traces for auth session runs.
+    "saveTraces": false,
+
+    // The type of auth session to use.
+    // "API" type requires implementing "auth-sessions/create.py" API to create/recreate the auth session programmatically.
+    // "MANUAL" type uses a recorder to manually create the auth session.
+    "type": "API",
+
+    // Recorder start URL for the recorder to navigate to when creating the auth session.
+    // Required if "type" is "MANUAL". Not used if "type" is "API".
+    "startUrl": "https://example.com/login",
+
+    // Recorder finish URL for the recorder. Once this URL is reached, the recorder stops and saves the auth session.
+    // Required if "type" is "MANUAL". Not used if "type" is "API".
+    "finishUrl": "https://example.com/dashboard",
+
+    // Recorder browser mode
+    // "fullscreen": Launches the browser in fullscreen mode.
+    // "kiosk": Launches the browser in kiosk mode (no address bar, no navigation controls).
+    // Only applicable for "MANUAL" type.
+    "browserMode": "fullscreen"
+  }
+
+  // API access settings
+  "apiAccess": {
+    // Whether to enable consumption through Intuned API. If this is false, the project can only be consumed through jobs.
+    // This is required for projects that use auth sessions.
+    "enabled": true
+  },
+
+  // Whether to run the deployed API in a headful browser. Running in headful can help with some anti-bot detections. However, it requires more resources and may work slower or crash if the machine size is "standard".
+  "headful": false,
+
+  // The region where your Intuned project is hosted.
+  // For a list of available regions, contact support or refer to the documentation.
+  // Optional - Default: "us"
+  "region": "us"
+}
+```
+
+"""

intuned_cli/controller/__test__/test_api.py

@@ -0,0 +1,529 @@
+from dataclasses import dataclass
+from typing import Any
+from typing import Generator
+from unittest.mock import AsyncMock
+from unittest.mock import Mock
+from unittest.mock import patch
+
+import pytest
+
+from runtime.types.run_types import PayloadToAppend
+from runtime.types.run_types import StorageState
+
+
+def get_mock_console():
+    """Create a mock console that tracks calls."""
+    mock_console = Mock()
+    mock_console.print = Mock()
+    return mock_console
+
+
+class AsyncContextManagerMock:
+    def __init__(self):
+        self.aenter_called = False
+        self.aexit_called = False
+        self.exception_info = None
+
+    async def __aenter__(self):
+        self.aenter_called = True
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any):
+        self.aexit_called = True
+        self.exception_info = (exc_type, exc_val, exc_tb)
+        # Return False/None to propagate exceptions
+        return False
+
+
+@dataclass
+class SharedMocks:
+    console: Mock
+    assert_api_file_exists: AsyncMock
+    register_get_auth_session_parameters: AsyncMock
+
+
+@pytest.fixture(autouse=True)
+def shared_mocks() -> Generator[SharedMocks, Any, None]:
+    """Mock dependencies for API controller tests."""
+    _mock_console_patch = patch("intuned_cli.controller.api.console", get_mock_console())
+    _mock_assert_api_patch = patch("intuned_cli.controller.api.assert_api_file_exists", new_callable=AsyncMock)
+    _mock_register_auth_patch = patch("intuned_cli.controller.api.register_get_auth_session_parameters")
+
+    with (
+        _mock_console_patch,
+        _mock_assert_api_patch as mock_assert_api,
+        _mock_register_auth_patch as mock_register_auth,
+    ):
+        # Setup default return values
+        mock_assert_api.return_value = None
+        mock_register_auth.return_value = None
+
+        yield SharedMocks(
+            console=get_mock_console(),
+            assert_api_file_exists=mock_assert_api,
+            register_get_auth_session_parameters=mock_register_auth,
+        )
+
+
+@dataclass
+class AttemptApiMocks:
+    extendable_timeout: AsyncMock
+    run_api: AsyncMock
+
+
+@pytest.fixture
+def attempt_api_mocks() -> Generator[AttemptApiMocks, Any, None]:
+    """Mock dependencies for attempt_api tests."""
+    _mock_timeout_patch = patch("intuned_cli.controller.api.extendable_timeout")
+    _mock_run_api_patch = patch("intuned_cli.controller.api.run_api", new_callable=AsyncMock)
+
+    with (
+        _mock_timeout_patch as mock_timeout,
+        _mock_run_api_patch as mock_run_api,
+    ):
+        # Setup default return values
+        mock_timeout.return_value = AsyncContextManagerMock()
+
+        # Mock run_api to return success by default
+        mock_result = Mock()
+        mock_result.result = "test_result"
+        mock_result.payload_to_append = []
+        mock_run_api.return_value = mock_result
+
+        yield AttemptApiMocks(
+            extendable_timeout=mock_timeout,
+            run_api=mock_run_api,
+        )
+
+
+@dataclass
+class ExecuteCLIMocks:
+    attempt_api: AsyncMock
+    execute_run_validate_auth_session_cli: AsyncMock
+    write_results_to_file: AsyncMock
+
+
+@pytest.fixture
+def execute_cli_mocks() -> Generator[ExecuteCLIMocks, Any, None]:
+    """Mock dependencies for execute_*_cli tests."""
+    _mock_validate_auth_patch = patch(
+        "intuned_cli.controller.api.execute_run_validate_auth_session_cli", new_callable=AsyncMock
+    )
+    _mock_run_api_patch = patch("intuned_cli.controller.api.attempt_api", new_callable=AsyncMock)
+    _mock_write_results_to_file_patch = patch(
+        "intuned_cli.controller.api.write_results_to_file", new_callable=AsyncMock
+    )
+
+    with (
+        _mock_validate_auth_patch as mock_validate_auth,
+        _mock_run_api_patch as mock_attempt_api,
+        _mock_write_results_to_file_patch as mock_write_results_to_file,
+    ):
+        # Setup default return values
+        mock_validate_auth.return_value = {"cookies": [], "storageState": {}}
+
+        # Mock run_api to return success by default
+        mock_attempt_api.return_value = ("test_result", [])
+
+        yield ExecuteCLIMocks(
+            execute_run_validate_auth_session_cli=mock_validate_auth,
+            attempt_api=mock_attempt_api,
+            write_results_to_file=mock_write_results_to_file,
+        )
+
+
+class TestAttemptApi:
+    """Test suite for attempt_api function."""
+
+    @pytest.mark.asyncio
+    async def test_attempt_api_calls_timeout_middleware_with_timeout(self, attempt_api_mocks: AttemptApiMocks):
+        """Test that attempt_api calls timeout middleware with the correct timeout."""
+        # Import inside test to avoid circular import issues
+        from intuned_cli.controller.api import attempt_api
+
+        await attempt_api(
+            api_name="testApi",
+            parameters={},
+            headless=False,
+            timeout=6000,
+        )
+
+        attempt_api_mocks.extendable_timeout.assert_called_once_with(6000)
+
+    @pytest.mark.asyncio
+    async def test_attempt_api_calls_run_api_with_correct_parameters_and_parses_proxy(
+        self, attempt_api_mocks: AttemptApiMocks
+    ):
+        """Test that attempt_api calls run_api with correct parameters and parses proxy."""
+        from intuned_cli.controller.api import attempt_api
+        from runtime.types.run_types import ProxyConfig
+
+        with patch("intuned_cli.controller.api.ProxyConfig.parse_from_str") as mock_parse_proxy:
+            proxy_config = ProxyConfig(
+                username="user",
+                password="pass",
+                server="proxy-server",
+            )
+            mock_parse_proxy.return_value = proxy_config
+
+            parameters: dict[Any, Any] = {}
+            auth = StorageState(cookies=[], origins=[], session_storage=[])
+            await attempt_api(
+                api_name="testApi",
+                parameters=parameters,
+                headless=False,
+                auth=auth,
+                proxy="proxy",
+                timeout=999999999,
+            )
+
+            # mock_parse_proxy.assert_called_once_with("proxy")
+            attempt_api_mocks.run_api.assert_called_once()
+
+            # Verify the call arguments
+            call_args = attempt_api_mocks.run_api.call_args[0][0]
+            assert call_args.automation_function.name == "api/testApi"
+            assert call_args.automation_function.params is parameters
+            assert call_args.run_options.headless is False
+            assert call_args.run_options.proxy == proxy_config
+            assert call_args.auth.session.state is auth
+            assert call_args.auth.run_check is False
+
+    @pytest.mark.asyncio
+    async def test_attempt_api_returns_result_and_extended_payloads_if_run_api_succeeds(
+        self, attempt_api_mocks: AttemptApiMocks
+    ):
+        """Test that attempt_api returns the result and extended payloads when run_api succeeds."""
+        from intuned_cli.controller.api import attempt_api
+
+        expected_result = {}
+        expected_payload_to_append = []
+
+        mock_result = Mock()
+        mock_result.result = expected_result
+        mock_result.payload_to_append = expected_payload_to_append
+        attempt_api_mocks.run_api.return_value = mock_result
+
+        result, payloads = await attempt_api(
+            api_name="testApi",
+            parameters="inputData",
+            headless=False,
+            timeout=999999999,
+        )
+
+        assert result is expected_result
+        assert payloads is expected_payload_to_append
+
+    @pytest.mark.asyncio
+    async def test_attempt_api_throws_error_when_run_api_fails_with_error(self, attempt_api_mocks: AttemptApiMocks):
+        """Test that attempt_api throws the error when run_api fails."""
+        from intuned_cli.controller.api import attempt_api
+
+        error = Exception("runApi failed")
+        attempt_api_mocks.run_api.side_effect = error
+
+        with pytest.raises(Exception, match="runApi failed"):
+            await attempt_api(
+                api_name="testApi",
+                parameters={},
+                headless=False,
+                timeout=999999999,
+            )
+
+
+class TestExecuteRunApiCli:
+    """Test suite for API controller functions."""
+
+    @pytest.mark.asyncio
+    async def test_execute_run_api_cli_calls_attempt_api_once_if_success(self, execute_cli_mocks: ExecuteCLIMocks):
+        """Test that execute_run_api_cli calls attemptApi once if successful."""
+        from intuned_cli.controller.api import execute_run_api_cli
+
+        await execute_run_api_cli(
+            api_name="testApi",
+            input_data={},
+            retries=3,
+            headless=False,
+            timeout=30,
+        )
+
+        execute_cli_mocks.attempt_api.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_execute_run_api_cli_stops_retrying_after_max_retries(self, execute_cli_mocks: ExecuteCLIMocks):
+        """Test that execute_run_api_cli stops retrying after max retries."""
+        from intuned_cli.controller.api import execute_run_api_cli
+        from intuned_cli.utils.error import CLIError
+        from runtime.errors.run_api_errors import AutomationError
+
+        execute_cli_mocks.attempt_api.side_effect = AutomationError(Exception("runApi failed"))
+
+        with pytest.raises(CLIError):
+            await execute_run_api_cli(
+                api_name="testApi",
+                input_data={},
+                retries=10,
+                headless=False,
+                timeout=30,
+            )
+
+        assert execute_cli_mocks.attempt_api.call_count == 10
+
+    @pytest.mark.asyncio
+    async def test_execute_run_api_cli_stops_retrying_on_non_automation_errors(
+        self, execute_cli_mocks: ExecuteCLIMocks
+    ):
+        """Test that execute_run_api_cli stops retrying on non-automation errors."""
+        from intuned_cli.controller.api import execute_run_api_cli
+
+        execute_cli_mocks.attempt_api.side_effect = Exception("runApi failed")
+
+        with pytest.raises(Exception, match="runApi failed"):
+            await execute_run_api_cli(
+                api_name="testApi",
+                input_data={},
+                retries=3,
+                headless=False,
+                timeout=30,
+            )
+
+        execute_cli_mocks.attempt_api.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_execute_run_api_cli_stops_retrying_on_success(self, execute_cli_mocks: ExecuteCLIMocks):
+        """Test that execute_run_api_cli stops retrying on success."""
+        from intuned_cli.controller.api import execute_run_api_cli
+        from runtime.errors.run_api_errors import AutomationError
+
+        execute_cli_mocks.attempt_api.side_effect = [
+            AutomationError(Exception("runApi failed")),
+            ("success", []),
+        ]
+
+        await execute_run_api_cli(
+            api_name="testApi",
+            input_data={},
+            retries=10,
+            headless=False,
+            timeout=30,
+        )
+
+        assert execute_cli_mocks.attempt_api.call_count == 2
+
+    @pytest.mark.asyncio
+    async def test_execute_run_api_cli_validates_auth_session_before_each_attempt_if_provided(
+        self, execute_cli_mocks: ExecuteCLIMocks
+    ):
+        """Test that execute_run_api_cli validates auth session before each attempt if provided."""
+        with patch(
+            "intuned_cli.controller.api.execute_run_validate_auth_session_cli", new_callable=AsyncMock
+        ) as mock_validate_auth:
+            from intuned_cli.controller.api import AuthSessionInput
+            from intuned_cli.controller.api import execute_run_api_cli
+            from runtime.errors.run_api_errors import AutomationError
+
+            execute_cli_mocks.attempt_api.side_effect = [
+                AutomationError(Exception("runApi failed")),
+                ("success", []),
+            ]
+
+            auth_session = AuthSessionInput(
+                id="authSessionId",
+                auto_recreate=False,
+                check_retries=1,
+                create_retries=2,
+            )
+
+            await execute_run_api_cli(
+                api_name="testApi",
+                input_data={},
+                auth_session=auth_session,
+                retries=10,
+                headless=False,
+                timeout=30,
+            )
+
+            assert mock_validate_auth.call_count == 2
+            # Verify the call arguments
+            call_args = mock_validate_auth.call_args
+            assert call_args[1]["id"] == "authSessionId"
+            assert call_args[1]["auto_recreate"] is False
+            assert call_args[1]["check_retries"] == 1
+            assert call_args[1]["create_retries"] == 2
+
+    @pytest.mark.asyncio
+    async def test_execute_run_api_cli_doesnt_validate_auth_session_if_not_provided(
+        self, execute_cli_mocks: ExecuteCLIMocks
+    ):
+        """Test that execute_run_api_cli doesn't validate auth session if not provided."""
+        from intuned_cli.controller.api import execute_run_api_cli
+
+        await execute_run_api_cli(
+            api_name="testApi",
+            input_data={},
+            retries=1,
+            headless=False,
+            timeout=30,
+        )
+
+        execute_cli_mocks.execute_run_validate_auth_session_cli.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_execute_run_api_cli_fails_if_auth_session_is_provided_but_not_valid(
+        self, execute_cli_mocks: ExecuteCLIMocks
+    ):
+        """Test that execute_run_api_cli fails if auth session is provided but not valid."""
+        from intuned_cli.controller.api import AuthSessionInput
+        from intuned_cli.controller.api import execute_run_api_cli
+        from intuned_cli.utils.error import CLIError
+
+        execute_cli_mocks.execute_run_validate_auth_session_cli.side_effect = CLIError("Auth session validation failed")
+
+        auth_session = AuthSessionInput(
+            id="authSessionId",
+            auto_recreate=False,
+            check_retries=1,
+            create_retries=2,
+        )
+
+        with pytest.raises(CLIError, match="Auth session validation failed"):
+            await execute_run_api_cli(
+                api_name="testApi",
+                input_data={},
+                auth_session=auth_session,
+                retries=10,
+                headless=False,
+                timeout=30,
+            )
+
+        # Verify auth validation was called
+        call_args = execute_cli_mocks.execute_run_validate_auth_session_cli.call_args
+        assert call_args[1]["id"] == "authSessionId"
+        assert call_args[1]["auto_recreate"] is False
+        assert call_args[1]["check_retries"] == 1
+        assert call_args[1]["create_retries"] == 2
+
+        execute_cli_mocks.attempt_api.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_execute_run_api_cli_writes_result_to_file_if_output_file_is_provided(
+        self, shared_mocks: SharedMocks, execute_cli_mocks: ExecuteCLIMocks
+    ):
+        """Test that execute_run_api_cli writes result to file if outputFile is provided."""
+
+        from intuned_cli.controller.api import execute_run_api_cli
+        from runtime.types.run_types import PayloadToAppend
+
+        execute_cli_mocks.attempt_api.return_value = (
+            "test_result",
+            [PayloadToAppend(api_name="test_api", parameters={"key": "value"})],
+        )
+
+        await execute_run_api_cli(
+            api_name="testApi",
+            input_data={},
+            output_file="output.json",
+            retries=1,
+            headless=False,
+            timeout=30,
+        )
+
+        execute_cli_mocks.write_results_to_file.assert_called_once()
+        call_args = execute_cli_mocks.write_results_to_file.call_args.kwargs
+        assert str(call_args["file_path"]) == "output.json"
+        assert call_args["result"] == "test_result"
+        assert call_args["extended_payloads"] == [PayloadToAppend(api_name="test_api", parameters={"key": "value"})]
+
+    @pytest.mark.asyncio
+    async def test_execute_run_api_cli_asserts_api_file_exists(
+        self, shared_mocks: SharedMocks, execute_cli_mocks: ExecuteCLIMocks
+    ):
+        """Test that execute_run_api_cli asserts API file exists."""
+        from intuned_cli.controller.api import execute_run_api_cli
+
+        await execute_run_api_cli(
+            api_name="testApi",
+            input_data={},
+            retries=1,
+            headless=False,
+            timeout=30,
+        )
+
+        shared_mocks.assert_api_file_exists.assert_called_once_with("api", "testApi")
+
+
+class TestExecuteAttemptApiCli:
+    """Test suite for execute_attempt_api_cli function."""
+
+    @pytest.mark.asyncio
+    async def test_execute_attempt_api_cli_calls_attempt_api_once(self, execute_cli_mocks: ExecuteCLIMocks):
+        """Test that executeAttemptApiCLI calls attemptApi once."""
+        from intuned_cli.controller.api import execute_attempt_api_cli
+        from runtime.errors.run_api_errors import AutomationError
+
+        await execute_attempt_api_cli(
+            api_name="testApi",
+            input_data={},
+            headless=False,
+            timeout=30,
+        )
+
+        execute_cli_mocks.attempt_api.assert_called_once()
+
+        # Test that it throws AutomationError when run_api fails
+        execute_cli_mocks.attempt_api.reset_mock()
+        execute_cli_mocks.attempt_api.side_effect = AutomationError(Exception("runApi failed"))
+
+        with pytest.raises(AutomationError):
+            await execute_attempt_api_cli(
+                api_name="testApi",
+                input_data={},
+                headless=False,
+                timeout=30,
+            )
+
+        execute_cli_mocks.attempt_api.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_execute_attempt_api_cli_writes_result_to_file_if_output_file_is_provided(
+        self, shared_mocks: SharedMocks, execute_cli_mocks: ExecuteCLIMocks
+    ):
+        """Test that executeAttemptApiCLI writes result to file if outputFile is provided."""
+
+        from intuned_cli.controller.api import execute_attempt_api_cli
+
+        execute_cli_mocks.attempt_api.return_value = (
+            "test_result",
+            [PayloadToAppend(api_name="test_api", parameters={"key": "value"})],
+        )
+
+        await execute_attempt_api_cli(
+            api_name="testApi",
+            input_data={},
+            output_file="output.json",
+            headless=False,
+            timeout=30,
+        )
+
+        # Verify file was written
+        execute_cli_mocks.write_results_to_file.assert_called_once()
+        call_args = execute_cli_mocks.write_results_to_file.call_args.kwargs
+        assert str(call_args["file_path"]) == "output.json"
+        assert call_args["result"] == "test_result"
+        assert call_args["extended_payloads"] == [PayloadToAppend(api_name="test_api", parameters={"key": "value"})]
+
+    @pytest.mark.asyncio
+    async def test_execute_attempt_api_cli_asserts_api_file_exists(
+        self, shared_mocks: SharedMocks, execute_cli_mocks: ExecuteCLIMocks
+    ):
+        """Test that executeAttemptApiCLI asserts API file exists."""
+        from intuned_cli.controller.api import execute_attempt_api_cli
+
+        await execute_attempt_api_cli(
+            api_name="testApi",
+            input_data={},
+            headless=False,
+            timeout=30,
+        )
+
+        shared_mocks.assert_api_file_exists.assert_called_once_with("api", "testApi")