Adds configurable state directory to client initialization (#6)

TL;DR
-----

Enables custom state directory configuration through an optional
parameter

Details
-------

Adds an optional `state_directory` parameter to both
`ReplicatedClient` and `AsyncReplicatedClient` to support scenarios
where the OS-standard location is ephemeral. When omitted, the
parameter defaults to None and the SDK uses existing platform-specific
logic unchanged. When provided, the SDK normalizes the path by
expanding tilde notation and resolving relative paths to absolute
ones, ensuring consistent behavior across different path styles.

This enhancement unblocks containerized deployments that need explicit
volume mount points, enables proper test isolation without filesystem
pollution, and supports multi-tenant architectures where state must
remain separate between customers. The implementation maintains the
SDK's silent failure philosophy for state operations, ensuring custom
directories integrate seamlessly with existing error handling
patterns.

Author: crdant

API_REFERENCE.md

@@ -56,15 +56,17 @@ ReplicatedClient(
     publishable_key: str,
     app_slug: str,
     base_url: str = "https://replicated.app",
-    timeout: float = 30.0
+    timeout: float = 30.0,
+    state_directory: Optional[str] = None
 )
 ```
 
 **Parameters:**
 - `publishable_key`: Your publishable API key from the Vendor Portal
 - `app_slug`: Your application slug
-- `base_url`: Base URL for the API (optional)
-- `timeout`: Request timeout in seconds (optional)
+- `base_url`: Base URL for the API (optional, defaults to "https://replicated.app")
+- `timeout`: Request timeout in seconds (optional, defaults to 30.0)
+- `state_directory`: Custom directory for state storage (optional). If not provided, uses platform-specific defaults. Supports `~` expansion and relative paths.
 
 #### Methods
 
@@ -160,11 +162,32 @@ The SDK automatically manages local state for:
 
 ### State Directory
 
-State is stored in platform-specific directories:
+State is stored in platform-specific directories by default:
 - **macOS:** `~/Library/Application Support/Replicated/<app_slug>`
 - **Linux:** `${XDG_STATE_HOME:-~/.local/state}/replicated/<app_slug>`
 - **Windows:** `%APPDATA%\Replicated\<app_slug>`
 
+You can override the state directory by providing the `state_directory` parameter:
+
+```python
+client = ReplicatedClient(
+    publishable_key="...",
+    app_slug="my-app",
+    state_directory="/custom/path/to/state"
+)
+```
+
+**Path Handling:**
+- The SDK automatically expands `~` to your home directory
+- Relative paths are resolved to absolute paths
+- The directory will be created automatically if it doesn't exist
+
+**Use Cases for Custom Directories:**
+- **Testing:** Use temporary directories for isolated test runs
+- **Containers:** Mount persistent volumes at custom paths
+- **Multi-tenant:** Isolate state per tenant in separate directories
+- **Development:** Use project-local directories for development state
+
 ## Machine Fingerprinting
 
 The SDK generates unique machine fingerprints using:
@@ -207,4 +230,4 @@ async with AsyncReplicatedClient(...) as client:
 
 ## Thread Safety
 
-The synchronous client creates a new HTTP client per request and is thread-safe. For high-concurrency applications, consider using the async client with a single event loop.
+The synchronous client creates a new HTTP client per request and is thread-safe. For high-concurrency applications, consider using the async client with a single event loop.

README.md

@@ -34,6 +34,34 @@ instance.set_status(InstanceStatus.RUNNING)
 instance.set_version("1.2.0")
 ```
 
+### Custom State Directory
+
+By default, the SDK stores state in platform-specific directories. You can override this for testing, containerization, or custom deployments:
+
+```python
+from replicated import ReplicatedClient
+
+# Use a custom directory (supports ~ and relative paths)
+client = ReplicatedClient(
+    publishable_key="replicated_pk_...",
+    app_slug="my-app",
+    state_directory="/var/lib/my-app/replicated-state"
+)
+
+# Or use a relative path (will be resolved to absolute)
+client = ReplicatedClient(
+    publishable_key="replicated_pk_...",
+    app_slug="my-app",
+    state_directory="./local-state"
+)
+```
+
+**When to use custom state directories:**
+- Testing with temporary directories
+- Docker containers with mounted volumes
+- Multi-tenant applications requiring isolated state
+- Development with project-local state
+
 ### Async Example
 
 ```python

replicated/async_client.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict
+from typing import Any, Dict, Optional
 
 from .http_client import AsyncHTTPClient
 from .services import AsyncCustomerService
@@ -14,17 +14,19 @@ def __init__(
         app_slug: str,
         base_url: str = "https://replicated.app",
         timeout: float = 30.0,
+        state_directory: Optional[str] = None,
     ) -> None:
         self.publishable_key = publishable_key
         self.app_slug = app_slug
         self.base_url = base_url
         self.timeout = timeout
+        self.state_directory = state_directory
 
         self.http_client = AsyncHTTPClient(
             base_url=base_url,
             timeout=timeout,
         )
-        self.state_manager = StateManager(app_slug)
+        self.state_manager = StateManager(app_slug, state_directory=state_directory)
         self.customer = AsyncCustomerService(self)
 
     async def __aenter__(self) -> "AsyncReplicatedClient":

replicated/client.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict
+from typing import Any, Dict, Optional
 
 from .http_client import SyncHTTPClient
 from .services import CustomerService
@@ -14,17 +14,19 @@ def __init__(
         app_slug: str,
         base_url: str = "https://replicated.app",
         timeout: float = 30.0,
+        state_directory: Optional[str] = None,
     ) -> None:
         self.publishable_key = publishable_key
         self.app_slug = app_slug
         self.base_url = base_url
         self.timeout = timeout
+        self.state_directory = state_directory
 
         self.http_client = SyncHTTPClient(
             base_url=base_url,
             timeout=timeout,
         )
-        self.state_manager = StateManager(app_slug)
+        self.state_manager = StateManager(app_slug, state_directory=state_directory)
         self.customer = CustomerService(self)
 
     def __enter__(self) -> "ReplicatedClient":

replicated/state.py

@@ -8,9 +8,16 @@
 class StateManager:
     """Manages local SDK state for idempotency and caching."""
 
-    def __init__(self, app_slug: str) -> None:
+    def __init__(self, app_slug: str, state_directory: Optional[str] = None) -> None:
         self.app_slug = app_slug
-        self._state_dir = self._get_state_directory()
+
+        # Use provided directory or derive platform-specific one
+        if state_directory:
+            # Normalize path: expand ~ and resolve relative paths
+            self._state_dir = Path(state_directory).expanduser().resolve()
+        else:
+            self._state_dir = self._get_state_directory()
+
         self._state_file = self._state_dir / "state.json"
         self._ensure_state_dir()
 

tests/test_client.py

@@ -1,3 +1,6 @@
+import os
+import tempfile
+from pathlib import Path
 from unittest.mock import Mock, patch
 
 import pytest
@@ -40,6 +43,59 @@ def test_customer_creation(self, mock_httpx):
         assert customer.customer_id == "customer_123"
         assert customer.email_address == "[email protected]"
 
+    def test_custom_state_directory(self):
+        """Test client with custom absolute state directory."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            custom_dir = Path(tmpdir) / "custom_state"
+            client = ReplicatedClient(
+                publishable_key="pk_test_123",
+                app_slug="my-app",
+                state_directory=str(custom_dir),
+            )
+            # Resolve both paths to handle symlinks
+            # (e.g., /var vs /private/var on macOS)
+            assert client.state_manager._state_dir == custom_dir.resolve()
+            expected_file = custom_dir.resolve() / "state.json"
+            assert client.state_manager._state_file == expected_file
+            assert custom_dir.exists()
+
+    def test_custom_state_directory_with_tilde(self):
+        """Test that ~ expansion works in custom state directory."""
+        client = ReplicatedClient(
+            publishable_key="pk_test_123",
+            app_slug="my-app",
+            state_directory="~/test-replicated-state",
+        )
+        # Should be expanded to actual home directory
+        assert "~" not in str(client.state_manager._state_dir)
+        assert str(client.state_manager._state_dir).startswith(str(Path.home()))
+
+    def test_custom_state_directory_relative_path(self):
+        """Test that relative paths are resolved in custom state directory."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            # Change to temp directory and use relative path
+            original_cwd = os.getcwd()
+            try:
+                os.chdir(tmpdir)
+                client = ReplicatedClient(
+                    publishable_key="pk_test_123",
+                    app_slug="my-app",
+                    state_directory="./relative_state",
+                )
+                # Should be resolved to absolute path
+                assert client.state_manager._state_dir.is_absolute()
+                assert str(tmpdir) in str(client.state_manager._state_dir)
+            finally:
+                os.chdir(original_cwd)
+
+    def test_default_state_directory_unchanged(self):
+        """Test that default behavior is unchanged when state_directory not provided."""
+        client = ReplicatedClient(publishable_key="pk_test_123", app_slug="my-app")
+        # Should use platform-specific directory
+        state_dir_str = str(client.state_manager._state_dir)
+        assert "my-app" in state_dir_str
+        assert "Replicated" in state_dir_str
+
 
 class TestAsyncReplicatedClient:
     @pytest.mark.asyncio
@@ -54,3 +110,59 @@ async def test_context_manager(self):
             publishable_key="pk_test_123", app_slug="my-app"
         ) as client:
             assert client is not None
+
+    @pytest.mark.asyncio
+    async def test_custom_state_directory(self):
+        """Test async client with custom state directory."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            custom_dir = Path(tmpdir) / "custom_state"
+            client = AsyncReplicatedClient(
+                publishable_key="pk_test_123",
+                app_slug="my-app",
+                state_directory=str(custom_dir),
+            )
+            # Resolve both paths to handle symlinks
+            # (e.g., /var vs /private/var on macOS)
+            assert client.state_manager._state_dir == custom_dir.resolve()
+            expected_file = custom_dir.resolve() / "state.json"
+            assert client.state_manager._state_file == expected_file
+            assert custom_dir.exists()
+
+    @pytest.mark.asyncio
+    async def test_custom_state_directory_with_tilde(self):
+        """Test that ~ expansion works in async client custom state directory."""
+        client = AsyncReplicatedClient(
+            publishable_key="pk_test_123",
+            app_slug="my-app",
+            state_directory="~/test-replicated-state",
+        )
+        # Should be expanded to actual home directory
+        assert "~" not in str(client.state_manager._state_dir)
+        assert str(client.state_manager._state_dir).startswith(str(Path.home()))
+
+    @pytest.mark.asyncio
+    async def test_custom_state_directory_relative_path(self):
+        """Test that relative paths are resolved in async client."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            # Change to temp directory and use relative path
+            original_cwd = os.getcwd()
+            try:
+                os.chdir(tmpdir)
+                client = AsyncReplicatedClient(
+                    publishable_key="pk_test_123",
+                    app_slug="my-app",
+                    state_directory="./relative_state",
+                )
+                # Should be resolved to absolute path
+                assert client.state_manager._state_dir.is_absolute()
+                assert str(tmpdir) in str(client.state_manager._state_dir)
+            finally:
+                os.chdir(original_cwd)
+
+    @pytest.mark.asyncio
+    async def test_default_state_directory_unchanged(self):
+        """Test that async client default behavior is unchanged."""
+        client = AsyncReplicatedClient(publishable_key="pk_test_123", app_slug="my-app")
+        state_dir_str = str(client.state_manager._state_dir)
+        assert "my-app" in state_dir_str
+        assert "Replicated" in state_dir_str