feat: Duration type rather than seconds

* Replace all duration parameters with Duration type

- Add Duration class with days, hours, minutes, seconds fields
- Add fluent builder methods: from_seconds(), from_minutes(), from_hours(), from_days()
- Update all customer-facing APIs to accept Duration instead of int seconds:
  - context.wait(duration)
  - InvokeConfig.timeout
  - CallbackConfig.timeout and heartbeat_timeout
  - RetryStrategyConfig.initial_delay and max_delay
  - WaitStrategyConfig.initial_delay, max_delay, and timeout
  - RetryDecision.delay
  - WaitDecision.delay
  - WaitForConditionDecision.delay
- Add *_seconds properties for internal backward compatibility
- Replace common values with fluent builders (e.g., Duration.from_minutes(5))

Author: Astraea Quinn S

src/aws_durable_execution_sdk_python/config.py

@@ -7,6 +7,8 @@
 from enum import Enum, StrEnum
 from typing import TYPE_CHECKING, Generic, TypeVar
 
+from aws_durable_execution_sdk_python.exceptions import ValidationError
+
 P = TypeVar("P")  # Payload type
 R = TypeVar("R")  # Result type
 T = TypeVar("T")
@@ -25,6 +27,42 @@
 Numeric = int | float  # deliberately leaving off complex
 
 
+@dataclass(frozen=True)
+class Duration:
+    """Represents a duration stored as total seconds."""
+
+    seconds: int = 0
+
+    def __post_init__(self):
+        if self.seconds < 0:
+            msg = "Duration seconds must be positive"
+            raise ValidationError(msg)
+
+    def to_seconds(self) -> int:
+        """Convert the duration to total seconds."""
+        return self.seconds
+
+    @classmethod
+    def from_seconds(cls, value: float) -> Duration:
+        """Create a Duration from total seconds."""
+        return cls(seconds=int(value))
+
+    @classmethod
+    def from_minutes(cls, value: float) -> Duration:
+        """Create a Duration from minutes."""
+        return cls(seconds=int(value * 60))
+
+    @classmethod
+    def from_hours(cls, value: float) -> Duration:
+        """Create a Duration from hours."""
+        return cls(seconds=int(value * 3600))
+
+    @classmethod
+    def from_days(cls, value: float) -> Duration:
+        """Create a Duration from days."""
+        return cls(seconds=int(value * 86400))
+
+
 @dataclass(frozen=True)
 class BatchedInput(Generic[T, U]):
     batch_input: T
@@ -343,19 +381,34 @@ class MapConfig:
 @dataclass
 class InvokeConfig(Generic[P, R]):
     # retry_strategy: Callable[[Exception, int], RetryDecision] | None = None
-    timeout_seconds: int = 0
+    timeout: Duration = field(default_factory=Duration)
     serdes_payload: SerDes[P] | None = None
     serdes_result: SerDes[R] | None = None
 
+    @property
+    def timeout_seconds(self) -> int:
+        """Get timeout in seconds."""
+        return self.timeout.to_seconds()
+
 
 @dataclass(frozen=True)
 class CallbackConfig:
     """Configuration for callbacks."""
 
-    timeout_seconds: int = 0
-    heartbeat_timeout_seconds: int = 0
+    timeout: Duration = field(default_factory=Duration)
+    heartbeat_timeout: Duration = field(default_factory=Duration)
     serdes: SerDes | None = None
 
+    @property
+    def timeout_seconds(self) -> int:
+        """Get timeout in seconds."""
+        return self.timeout.to_seconds()
+
+    @property
+    def heartbeat_timeout_seconds(self) -> int:
+        """Get heartbeat timeout in seconds."""
+        return self.heartbeat_timeout.to_seconds()
+
 
 @dataclass(frozen=True)
 class WaitForCallbackConfig(CallbackConfig):

src/aws_durable_execution_sdk_python/context.py

@@ -8,6 +8,7 @@
     BatchedInput,
     CallbackConfig,
     ChildConfig,
+    Duration,
     InvokeConfig,
     MapConfig,
     ParallelConfig,
@@ -447,15 +448,16 @@ def step(
             context_logger=self.logger,
         )
 
-    def wait(self, seconds: int, name: str | None = None) -> None:
+    def wait(self, duration: Duration, name: str | None = None) -> None:
         """Wait for a specified amount of time.
 
         Args:
-            seconds: Time to wait in seconds
+            duration: Duration to wait
             name: Optional name for the wait step
         """
+        seconds = duration.to_seconds()
         if seconds < 1:
-            msg = "seconds must be an integer greater than 0"
+            msg = "duration must be at least 1 second"
             raise ValidationError(msg)
         wait_handler(
             seconds=seconds,

src/aws_durable_execution_sdk_python/retries.py

@@ -7,7 +7,7 @@
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING
 
-from aws_durable_execution_sdk_python.config import JitterStrategy
+from aws_durable_execution_sdk_python.config import Duration, JitterStrategy
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -20,31 +20,48 @@ class RetryDecision:
     """Decision about whether to retry a step and with what delay."""
 
     should_retry: bool
-    delay_seconds: int
+    delay: Duration
+
+    @property
+    def delay_seconds(self) -> int:
+        """Get delay in seconds."""
+        return self.delay.to_seconds()
 
     @classmethod
-    def retry(cls, delay_seconds: int) -> RetryDecision:
+    def retry(cls, delay: Duration) -> RetryDecision:
         """Create a retry decision."""
-        return cls(should_retry=True, delay_seconds=delay_seconds)
+        return cls(should_retry=True, delay=delay)
 
     @classmethod
     def no_retry(cls) -> RetryDecision:
         """Create a no-retry decision."""
-        return cls(should_retry=False, delay_seconds=0)
+        return cls(should_retry=False, delay=Duration())
 
 
 @dataclass
 class RetryStrategyConfig:
     max_attempts: int = 3
-    initial_delay_seconds: int = 5
-    max_delay_seconds: int = 300  # 5 minutes
+    initial_delay: Duration = field(default_factory=lambda: Duration.from_seconds(5))
+    max_delay: Duration = field(
+        default_factory=lambda: Duration.from_minutes(5)
+    )  # 5 minutes
     backoff_rate: Numeric = 2.0
     jitter_strategy: JitterStrategy = field(default=JitterStrategy.FULL)
     retryable_errors: list[str | re.Pattern] = field(
         default_factory=lambda: [re.compile(r".*")]
     )
     retryable_error_types: list[type[Exception]] = field(default_factory=list)
 
+    @property
+    def initial_delay_seconds(self) -> int:
+        """Get initial delay in seconds."""
+        return self.initial_delay.to_seconds()
+
+    @property
+    def max_delay_seconds(self) -> int:
+        """Get max delay in seconds."""
+        return self.max_delay.to_seconds()
+
 
 def create_retry_strategy(
     config: RetryStrategyConfig,
@@ -82,7 +99,7 @@ def retry_strategy(error: Exception, attempts_made: int) -> RetryDecision:
         delay_with_jitter = math.ceil(delay_with_jitter)
         final_delay = max(1, delay_with_jitter)
 
-        return RetryDecision.retry(round(final_delay))
+        return RetryDecision.retry(Duration(seconds=round(final_delay)))
 
     return retry_strategy
 
@@ -101,8 +118,8 @@ def default(cls) -> Callable[[Exception, int], RetryDecision]:
         return create_retry_strategy(
             RetryStrategyConfig(
                 max_attempts=6,
-                initial_delay_seconds=5,
-                max_delay_seconds=60,
+                initial_delay=Duration.from_seconds(5),
+                max_delay=Duration.from_minutes(1),
                 backoff_rate=2,
                 jitter_strategy=JitterStrategy.FULL,
             )
@@ -123,8 +140,8 @@ def resource_availability(cls) -> Callable[[Exception, int], RetryDecision]:
         return create_retry_strategy(
             RetryStrategyConfig(
                 max_attempts=5,
-                initial_delay_seconds=5,
-                max_delay_seconds=300,
+                initial_delay=Duration.from_seconds(5),
+                max_delay=Duration.from_minutes(5),
                 backoff_rate=2,
             )
         )
@@ -135,8 +152,8 @@ def critical(cls) -> Callable[[Exception, int], RetryDecision]:
         return create_retry_strategy(
             RetryStrategyConfig(
                 max_attempts=10,
-                initial_delay_seconds=1,
-                max_delay_seconds=60,
+                initial_delay=Duration.from_seconds(1),
+                max_delay=Duration.from_minutes(1),
                 backoff_rate=1.5,
                 jitter_strategy=JitterStrategy.NONE,
             )

src/aws_durable_execution_sdk_python/types.py

@@ -13,6 +13,7 @@
         BatchedInput,
         CallbackConfig,
         ChildConfig,
+        Duration,
         MapConfig,
         ParallelConfig,
         StepConfig,
@@ -126,7 +127,7 @@ def parallel(
         ...  # pragma: no cover
 
     @abstractmethod
-    def wait(self, seconds: int, name: str | None = None) -> None:
+    def wait(self, duration: Duration, name: str | None = None) -> None:
         """Wait for a specified amount of time."""
         ...  # pragma: no cover
 

src/aws_durable_execution_sdk_python/waits.py

@@ -5,7 +5,7 @@
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Generic
 
-from aws_durable_execution_sdk_python.config import JitterStrategy, T
+from aws_durable_execution_sdk_python.config import Duration, JitterStrategy, T
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -20,28 +20,52 @@ class WaitDecision:
     """Decision about whether to wait a step and with what delay."""
 
     should_wait: bool
-    delay_seconds: int
+    delay: Duration
+
+    @property
+    def delay_seconds(self) -> int:
+        """Get delay in seconds."""
+        return self.delay.to_seconds()
 
     @classmethod
-    def wait(cls, delay_seconds: int) -> WaitDecision:
+    def wait(cls, delay: Duration) -> WaitDecision:
         """Create a wait decision."""
-        return cls(should_wait=True, delay_seconds=delay_seconds)
+        return cls(should_wait=True, delay=delay)
 
     @classmethod
     def no_wait(cls) -> WaitDecision:
         """Create a no-wait decision."""
-        return cls(should_wait=False, delay_seconds=0)
+        return cls(should_wait=False, delay=Duration())
 
 
 @dataclass
 class WaitStrategyConfig(Generic[T]):
     should_continue_polling: Callable[[T], bool]
     max_attempts: int = 60
-    initial_delay_seconds: int = 5
-    max_delay_seconds: int = 300  # 5 minutes
+    initial_delay: Duration = field(default_factory=lambda: Duration.from_seconds(5))
+    max_delay: Duration = field(
+        default_factory=lambda: Duration.from_minutes(5)
+    )  # 5 minutes
     backoff_rate: Numeric = 1.5
     jitter_strategy: JitterStrategy = field(default=JitterStrategy.FULL)
-    timeout_seconds: int | None = None  # Not implemented yet
+    timeout: Duration | None = None  # Not implemented yet
+
+    @property
+    def initial_delay_seconds(self) -> int:
+        """Get initial delay in seconds."""
+        return self.initial_delay.to_seconds()
+
+    @property
+    def max_delay_seconds(self) -> int:
+        """Get max delay in seconds."""
+        return self.max_delay.to_seconds()
+
+    @property
+    def timeout_seconds(self) -> int | None:
+        """Get timeout in seconds."""
+        if self.timeout is None:
+            return None
+        return self.timeout.to_seconds()
 
 
 def create_wait_strategy(
@@ -69,7 +93,7 @@ def wait_strategy(result: T, attempts_made: int) -> WaitDecision:
         # Ensure delay is an integer >= 1
         final_delay = max(1, round(delay_with_jitter))
 
-        return WaitDecision.wait(final_delay)
+        return WaitDecision.wait(Duration(seconds=final_delay))
 
     return wait_strategy
 
@@ -79,17 +103,22 @@ class WaitForConditionDecision:
     """Decision about whether to continue waiting."""
 
     should_continue: bool
-    delay_seconds: int
+    delay: Duration
+
+    @property
+    def delay_seconds(self) -> int:
+        """Get delay in seconds."""
+        return self.delay.to_seconds()
 
     @classmethod
-    def continue_waiting(cls, delay_seconds: int) -> WaitForConditionDecision:
+    def continue_waiting(cls, delay: Duration) -> WaitForConditionDecision:
         """Create a decision to continue waiting for delay_seconds."""
-        return cls(should_continue=True, delay_seconds=delay_seconds)
+        return cls(should_continue=True, delay=delay)
 
     @classmethod
     def stop_polling(cls) -> WaitForConditionDecision:
         """Create a decision to stop polling."""
-        return cls(should_continue=False, delay_seconds=-1)
+        return cls(should_continue=False, delay=Duration())
 
 
 @dataclass(frozen=True)

tests/config_test.py

@@ -9,6 +9,7 @@
     CheckpointMode,
     ChildConfig,
     CompletionConfig,
+    Duration,
     ItemBatcher,
     ItemsPerBatchUnit,
     MapConfig,
@@ -85,7 +86,7 @@ def test_parallel_config_defaults():
 
 def test_wait_for_condition_decision_continue():
     """Test WaitForConditionDecision.continue_waiting factory method."""
-    decision = WaitForConditionDecision.continue_waiting(30)
+    decision = WaitForConditionDecision.continue_waiting(Duration.from_seconds(30))
     assert decision.should_continue is True
     assert decision.delay_seconds == 30
 
@@ -94,14 +95,14 @@ def test_wait_for_condition_decision_stop():
     """Test WaitForConditionDecision.stop_polling factory method."""
     decision = WaitForConditionDecision.stop_polling()
     assert decision.should_continue is False
-    assert decision.delay_seconds == -1
+    assert decision.delay_seconds == 0
 
 
 def test_wait_for_condition_config():
     """Test WaitForConditionConfig with custom values."""
 
     def wait_strategy(state, attempt):
-        return WaitForConditionDecision.continue_waiting(10)
+        return WaitForConditionDecision.continue_waiting(Duration.from_seconds(10))
 
     serdes = Mock()
     config = WaitForConditionConfig(
@@ -237,7 +238,9 @@ def test_callback_config_with_values():
     """Test CallbackConfig with custom values."""
     serdes = Mock()
     config = CallbackConfig(
-        timeout_seconds=30, heartbeat_timeout_seconds=10, serdes=serdes
+        timeout=Duration.from_seconds(30),
+        heartbeat_timeout=Duration.from_seconds(10),
+        serdes=serdes,
     )
     assert config.timeout_seconds == 30
     assert config.heartbeat_timeout_seconds == 10