actionbox-sdk 0.1.6__py3-none-any.whl

actionbox/__init__.py

@@ -0,0 +1,1061 @@
+from __future__ import annotations
+
+import ipaddress
+import random
+import secrets
+import threading
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from typing import Any, Literal, NotRequired, Self, TypedDict, cast
+from urllib.parse import quote, urlsplit
+
+import httpx
+
+__version__ = "0.1.6"
+_MAX_RESPONSE_BYTES = 1_048_576
+_MAX_RETRY_DELAY = 30.0
+
+OptionStyle = Literal["default", "primary", "destructive"]
+
+
+class ActionOption(TypedDict):
+    """An option used by a single-choice or multi-choice interaction."""
+
+    id: str
+    label: str
+    style: NotRequired[OptionStyle]
+    sort_order: NotRequired[int]
+
+
+ActionOptionInput = ActionOption
+
+
+class BooleanInteraction(TypedDict):
+    type: Literal["boolean"]
+    label: str
+    true_label: NotRequired[str]
+    false_label: NotRequired[str]
+
+
+class SingleChoiceInteraction(TypedDict):
+    type: Literal["single_choice"]
+    label: str
+    options: list[ActionOption]
+
+
+class MultiChoiceInteraction(TypedDict):
+    type: Literal["multi_choice"]
+    label: str
+    options: list[ActionOption]
+    min_selections: NotRequired[int]
+    max_selections: NotRequired[int | None]
+
+
+class TextInteraction(TypedDict):
+    type: Literal["text"]
+    label: str
+    placeholder: NotRequired[str | None]
+    multiline: NotRequired[bool]
+    min_length: NotRequired[int]
+    max_length: NotRequired[int]
+
+
+class IntegerInteraction(TypedDict):
+    type: Literal["integer"]
+    label: str
+    min: NotRequired[int | None]
+    max: NotRequired[int | None]
+    step: NotRequired[int]
+    unit: NotRequired[str | None]
+
+
+class NumberInteraction(TypedDict):
+    type: Literal["number"]
+    label: str
+    min: NotRequired[int | float | None]
+    max: NotRequired[int | float | None]
+    step: NotRequired[int | float]
+    unit: NotRequired[str | None]
+
+
+class RatingInteraction(TypedDict):
+    type: Literal["rating"]
+    label: str
+    min: NotRequired[int]
+    max: NotRequired[int]
+    low_label: NotRequired[str | None]
+    high_label: NotRequired[str | None]
+
+
+class FormBooleanField(BooleanInteraction):
+    id: str
+    required: NotRequired[bool]
+
+
+class FormSingleChoiceField(SingleChoiceInteraction):
+    id: str
+    required: NotRequired[bool]
+
+
+class FormMultiChoiceField(MultiChoiceInteraction):
+    id: str
+    required: NotRequired[bool]
+
+
+class FormTextField(TextInteraction):
+    id: str
+    required: NotRequired[bool]
+
+
+class FormIntegerField(IntegerInteraction):
+    id: str
+    required: NotRequired[bool]
+
+
+class FormNumberField(NumberInteraction):
+    id: str
+    required: NotRequired[bool]
+
+
+class FormRatingField(RatingInteraction):
+    id: str
+    required: NotRequired[bool]
+
+
+FormField = (
+    FormBooleanField
+    | FormSingleChoiceField
+    | FormMultiChoiceField
+    | FormTextField
+    | FormIntegerField
+    | FormNumberField
+    | FormRatingField
+)
+
+
+class FormInteraction(TypedDict):
+    type: Literal["form"]
+    label: str
+    fields: list[FormField]
+
+
+TypedInteraction = (
+    BooleanInteraction
+    | SingleChoiceInteraction
+    | MultiChoiceInteraction
+    | TextInteraction
+    | IntegerInteraction
+    | NumberInteraction
+    | RatingInteraction
+    | FormInteraction
+)
+Interaction = TypedInteraction
+
+
+class BooleanResponse(TypedDict):
+    type: Literal["boolean"]
+    value: bool
+
+
+class TextResponse(TypedDict):
+    type: Literal["text"]
+    value: str
+
+
+class IntegerResponse(TypedDict):
+    type: Literal["integer"]
+    value: int
+
+
+class NumberResponse(TypedDict):
+    type: Literal["number"]
+    value: int | float
+
+
+class RatingResponse(TypedDict):
+    type: Literal["rating"]
+    value: int
+
+
+class SingleChoiceResponse(TypedDict):
+    type: Literal["single_choice"]
+    value: str
+
+
+class MultiChoiceResponse(TypedDict):
+    type: Literal["multi_choice"]
+    value: list[str]
+
+
+class FormResponse(TypedDict):
+    type: Literal["form"]
+    values: dict[str, Any]
+
+
+TypedResponse = (
+    BooleanResponse
+    | TextResponse
+    | IntegerResponse
+    | NumberResponse
+    | RatingResponse
+    | SingleChoiceResponse
+    | MultiChoiceResponse
+    | FormResponse
+)
+InteractionResponse = TypedResponse
+Response = TypedResponse
+
+
+class ActionCreateInput(TypedDict, total=False):
+    """The JSON fields accepted by ``Actionbox.create``."""
+
+    title: str
+    description: str
+    priority: Literal["low", "normal", "high", "urgent"]
+    open_url: str
+    dedupe_key: str
+    callback_url: str
+    expires_at: str
+    on_expire: dict[str, Any]
+    context: list[dict[str, Any]]
+    options: list[ActionOption]
+    interaction: TypedInteraction
+    metadata: dict[str, Any]
+    run_id: str
+
+
+class ResolveInput(TypedDict, total=False):
+    """The JSON fields accepted by the generic resolve endpoint."""
+
+    action_version: int
+    fingerprint: str
+    option_id: str
+    response: TypedResponse
+    reason: str
+
+
+class ActionOutcome(TypedDict):
+    id: str
+    action_id: str
+    status: Literal["success", "failed"]
+    duration_ms: int | None
+    rollback: bool
+    reason_code: str | None
+    action_version: int
+    fingerprint: str
+    created_at: str
+
+
+class ActionboxError(RuntimeError):
+    def __init__(self, message: str, code: str = "UNKNOWN", status: int = 500) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+
+RunStatus = Literal["queued", "running", "waiting", "succeeded", "failed", "cancelled"]
+
+
+@dataclass
+class AgentRun:
+    """One autonomous task; progress sequencing is handled for the caller."""
+
+    client: Actionbox
+    data: dict[str, Any]
+
+    @property
+    def id(self) -> str:
+        return self.data["id"]
+
+    @property
+    def status(self) -> RunStatus:
+        return cast(RunStatus, self.data["status"])
+
+    @property
+    def progress_sequence(self) -> int:
+        return int(self.data.get("progress_sequence", 0))
+
+    @property
+    def stalled(self) -> bool:
+        return bool(self.data.get("stalled", False))
+
+    @property
+    def stall_action_id(self) -> str | None:
+        value = self.data.get("stall_action_id")
+        return value if isinstance(value, str) else None
+
+    def progress(
+        self,
+        *,
+        status: Literal["running", "waiting"] | None = None,
+        stage: str | None = None,
+        checkpoint: str | None = None,
+        cancel_event: threading.Event | None = None,
+    ) -> AgentRun:
+        payload: dict[str, Any] = {"sequence": self.progress_sequence + 1}
+        if status is not None:
+            payload["status"] = status
+        if stage is not None:
+            payload["stage"] = stage
+        if checkpoint is not None:
+            payload["checkpoint"] = checkpoint
+        if len(payload) == 1:
+            raise ValueError("provide status, stage, or checkpoint")
+        self.data = cast(
+            dict[str, Any],
+            self.client._request(
+                "PATCH",
+                f"/v1/source/runs/{quote(self.id, safe='')}/progress",
+                json=payload,
+                headers={"Idempotency-Key": f"run-progress-{self.id}-{payload['sequence']}"},
+                cancel_event=cancel_event,
+            ),
+        )
+        return self
+
+    def complete(
+        self,
+        status: Literal["succeeded", "failed", "cancelled"] = "succeeded",
+        *,
+        reason_code: str | None = None,
+        cancel_event: threading.Event | None = None,
+    ) -> AgentRun:
+        self.data = cast(
+            dict[str, Any],
+            self.client._request(
+                "POST",
+                f"/v1/source/runs/{quote(self.id, safe='')}/complete",
+                json={
+                    "status": status,
+                    "progress_sequence": self.progress_sequence,
+                    "reason_code": reason_code,
+                },
+                headers={"Idempotency-Key": f"run-complete-{self.id}"},
+                cancel_event=cancel_event,
+            ),
+        )
+        return self
+
+
+class RunsResource:
+    def __init__(self, client: Actionbox) -> None:
+        self.client = client
+
+    def start(
+        self,
+        *,
+        external_id: str,
+        agent_name: str,
+        title: str,
+        cancel_event: threading.Event | None = None,
+        **payload: Any,
+    ) -> AgentRun:
+        data = self.client._request(
+            "POST",
+            "/v1/runs",
+            json={
+                "external_id": external_id,
+                "agent_name": agent_name,
+                "title": title,
+                **payload,
+            },
+            headers={"Idempotency-Key": f"run-start-{external_id}"},
+            cancel_event=cancel_event,
+        )
+        return AgentRun(self.client, cast(dict[str, Any], data))
+
+    def get(
+        self,
+        run_id: str,
+        *,
+        cancel_event: threading.Event | None = None,
+    ) -> AgentRun:
+        data = self.client._request(
+            "GET",
+            f"/v1/source/runs/{quote(run_id, safe='')}",
+            cancel_event=cancel_event,
+        )
+        return AgentRun(self.client, cast(dict[str, Any], data))
+
+
+WatchStatus = Literal["new", "healthy", "down", "paused"]
+WatchScheduleType = Literal["interval", "cron"]
+WatchSignalMethod = Literal["any", "post"]
+
+
+class WatchCreateInput(TypedDict, total=False):
+    source_id: str
+    name: str
+    schedule_type: WatchScheduleType
+    interval_seconds: int
+    cron_expression: str
+    timezone: str
+    grace_seconds: int
+    max_runtime_seconds: int
+    priority: Literal["low", "normal", "high", "urgent"]
+    runbook_url: str
+    signal_method: WatchSignalMethod
+
+
+@dataclass
+class Watch:
+    """Safe Watch state. The raw heartbeat URL is only present on creation."""
+
+    client: Actionbox
+    data: dict[str, Any]
+
+    @property
+    def id(self) -> str:
+        return self.data["id"]
+
+    @property
+    def name(self) -> str:
+        return self.data["name"]
+
+    @property
+    def status(self) -> str:
+        return self.data["status"]
+
+    @property
+    def heartbeat_url(self) -> str | None:
+        value = self.data.get("heartbeat_url")
+        return value if isinstance(value, str) else None
+
+
+class WatchesResource:
+    def __init__(self, client: Actionbox) -> None:
+        self.client = client
+
+    def list(self, *, cancel_event: threading.Event | None = None) -> list[Watch]:
+        data = self.client._request("GET", "/v1/source/watches", cancel_event=cancel_event)
+        if not isinstance(data, list):
+            raise ActionboxError("Actionbox returned an invalid Watch list.", "INVALID_RESPONSE", 200)
+        return [Watch(self.client, item) for item in data if isinstance(item, dict)]
+
+    def create(self, *, cancel_event: threading.Event | None = None, **payload: Any) -> Watch:
+        data = self.client._request(
+            "POST",
+            "/v1/source/watches",
+            json=payload,
+            cancel_event=cancel_event,
+        )
+        return Watch(self.client, data)
+
+    def pause(self, watch_id: str, *, cancel_event: threading.Event | None = None) -> Watch:
+        data = self.client._request(
+            "POST",
+            f"/v1/source/watches/{quote(watch_id, safe='')}/pause",
+            cancel_event=cancel_event,
+        )
+        return Watch(self.client, data)
+
+    def resume(self, watch_id: str, *, cancel_event: threading.Event | None = None) -> Watch:
+        data = self.client._request(
+            "POST",
+            f"/v1/source/watches/{quote(watch_id, safe='')}/resume",
+            cancel_event=cancel_event,
+        )
+        return Watch(self.client, data)
+
+    def rotate_token(self, watch_id: str, *, cancel_event: threading.Event | None = None) -> Watch:
+        data = self.client._request(
+            "POST",
+            f"/v1/source/watches/{quote(watch_id, safe='')}/token/rotate",
+            cancel_event=cancel_event,
+        )
+        return Watch(self.client, data)
+
+    def archive(self, watch_id: str, *, cancel_event: threading.Event | None = None) -> None:
+        self.client._request(
+            "DELETE",
+            f"/v1/source/watches/{quote(watch_id, safe='')}",
+            cancel_event=cancel_event,
+        )
+
+
+@dataclass
+class Action:
+    client: Actionbox
+    data: dict[str, Any]
+
+    @property
+    def id(self) -> str:
+        return self.data["id"]
+
+    @property
+    def status(self) -> str:
+        return self.data["status"]
+
+    @property
+    def environment(self) -> str:
+        value = self.data.get("environment", "live")
+        return value if value in {"live", "test"} else "live"
+
+    @property
+    def action_version(self) -> int:
+        return int(self.data.get("action_version", 1))
+
+    @property
+    def fingerprint(self) -> str | None:
+        value = self.data.get("fingerprint")
+        return value if isinstance(value, str) else None
+
+    @property
+    def decision(self) -> str | None:
+        return self.data.get("resolution_option_id")
+
+    @property
+    def interaction(self) -> TypedInteraction | None:
+        return cast(TypedInteraction | None, self.data.get("interaction"))
+
+    @property
+    def response(self) -> TypedResponse | None:
+        return cast(TypedResponse | None, self.data.get("response"))
+
+    @property
+    def receipt(self) -> str | None:
+        value = self.data.get("receipt")
+        return value if isinstance(value, str) else None
+
+    @property
+    def outcome(self) -> ActionOutcome | None:
+        return cast(ActionOutcome | None, self.data.get("outcome"))
+
+    def report_outcome(
+        self,
+        status: Literal["success", "failed"],
+        *,
+        duration_ms: int | None = None,
+        rollback: bool = False,
+        reason_code: str | None = None,
+        cancel_event: threading.Event | None = None,
+    ) -> ActionOutcome:
+        fingerprint = self.fingerprint
+        if fingerprint is None:
+            raise ValueError("the Action has no fingerprint to bind the outcome")
+        return self.client.report_outcome(
+            self.id,
+            status,
+            action_version=self.action_version,
+            fingerprint=fingerprint,
+            duration_ms=duration_ms,
+            rollback=rollback,
+            reason_code=reason_code,
+            cancel_event=cancel_event,
+        )
+
+    def refresh(self, *, cancel_event: threading.Event | None = None) -> Action:
+        self.data = self.client.get(self.id, cancel_event=cancel_event).data
+        return self
+
+    def wait(
+        self,
+        timeout: float = 3600,
+        poll_interval: float = 2,
+        *,
+        cancel_event: threading.Event | None = None,
+    ) -> str | TypedResponse | None:
+        if timeout <= 0:
+            raise ValueError("timeout must be greater than zero")
+        if poll_interval <= 0:
+            raise ValueError("poll_interval must be greater than zero")
+        deadline = time.monotonic() + timeout
+        while self.status == "open" and time.monotonic() < deadline:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            wait_sec = min(int(max(1, min(remaining, poll_interval * 5))), 30)
+            if cancel_event is not None and cancel_event.is_set():
+                raise ActionboxError("Actionbox wait was cancelled.", "ABORTED", 0)
+            self.data = self.client.get(self.id, wait_seconds=wait_sec, cancel_event=cancel_event).data
+            if self.status != "open" or time.monotonic() >= deadline:
+                break
+        if self.status == "open":
+            return None
+        # Return a concise string for single-choice Actions and the typed
+        # response for boolean, numeric, text, multi-choice, and form inputs.
+        return self.decision if self.decision is not None else self.response
+
+
+class ActionsResource:
+    def __init__(self, client: Actionbox) -> None:
+        self.client = client
+
+    def create(self, **payload: Any) -> Action:
+        return self.client.create(**payload)
+
+    def resolve(
+        self,
+        action_id: str,
+        option_id: str | ResolveInput | TypedResponse | None = None,
+        reason: str | None = None,
+        *,
+        response: TypedResponse | None = None,
+        action_version: int | None = None,
+        fingerprint: str | None = None,
+    ) -> Action:
+        return self.client.resolve(
+            action_id,
+            option_id,
+            reason,
+            response=response,
+            action_version=action_version,
+            fingerprint=fingerprint,
+        )
+
+    def report_outcome(
+        self,
+        action_id: str,
+        status: Literal["success", "failed"],
+        *,
+        action_version: int,
+        fingerprint: str,
+        duration_ms: int | None = None,
+        rollback: bool = False,
+        reason_code: str | None = None,
+    ) -> ActionOutcome:
+        return self.client.report_outcome(
+            action_id,
+            status,
+            action_version=action_version,
+            fingerprint=fingerprint,
+            duration_ms=duration_ms,
+            rollback=rollback,
+            reason_code=reason_code,
+        )
+
+
+class Actionbox:
+    """Small synchronous client for source-authenticated Actionbox APIs."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.actionbox.cloud",
+        timeout: float = 10,
+        max_retries: int = 2,
+        *,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        if not api_key or any(character.isspace() for character in api_key):
+            raise ValueError("api_key must be a non-empty token without whitespace")
+        if timeout <= 0:
+            raise ValueError("timeout must be greater than zero")
+        if not isinstance(max_retries, int) or not 0 <= max_retries <= 5:
+            raise ValueError("max_retries must be an integer from 0 through 5")
+        self.base_url = _validate_base_url(base_url)
+        self.http = http_client or httpx.Client(timeout=timeout)
+        self._owns_http_client = http_client is None
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.headers = {
+            "Authorization": f"Bearer {api_key}",
+            "X-Actionbox-Client": f"python-sdk/{__version__}",
+        }
+        self.actions = ActionsResource(self)
+        self.watches = WatchesResource(self)
+        self.runs = RunsResource(self)
+
+    def close(self) -> None:
+        if self._owns_http_client:
+            self.http.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        cancel_event: threading.Event | None = None,
+        timeout: float | None = None,
+    ) -> dict[str, Any] | list[Any]:
+        request_headers = {**self.headers, **(headers or {})}
+        retryable = method.upper() in {"GET", "HEAD", "OPTIONS"} or "Idempotency-Key" in request_headers
+        attempts = self.max_retries + 1 if retryable else 1
+
+        for attempt in range(attempts):
+            _raise_if_cancelled(cancel_event)
+            request = self.http.build_request(
+                method,
+                f"{self.base_url}{path}",
+                json=json,
+                headers=request_headers,
+                timeout=timeout if timeout is not None else self.timeout,
+            )
+            try:
+                response = self.http.send(request, stream=True)
+            except httpx.TimeoutException as exc:
+                if retryable and attempt + 1 < attempts:
+                    _wait_before_retry(attempt, None, cancel_event)
+                    continue
+                raise ActionboxError("Actionbox request timed out.", "TIMEOUT", 0) from exc
+            except httpx.TransportError as exc:
+                if retryable and attempt + 1 < attempts:
+                    _wait_before_retry(attempt, None, cancel_event)
+                    continue
+                raise ActionboxError("Actionbox network request failed.", "NETWORK_ERROR", 0) from exc
+
+            try:
+                raw_body = _read_bounded_body(response)
+            finally:
+                response.close()
+
+            if retryable and attempt + 1 < attempts and (response.status_code == 429 or response.status_code >= 500):
+                _wait_before_retry(attempt, response.headers.get("Retry-After"), cancel_event)
+                continue
+
+            body = _parse_response_body(raw_body, response.status_code)
+            if not response.is_success:
+                error = body.get("error", {}) if isinstance(body.get("error"), dict) else {}
+                detail = body.get("detail") if isinstance(body.get("detail"), str) else None
+                raise ActionboxError(
+                    error.get("message", detail or "Actionbox request failed."),
+                    error.get("code", "UNKNOWN"),
+                    response.status_code,
+                )
+            data = body.get("data", body)
+            if not isinstance(data, (dict, list)):
+                raise ActionboxError("Actionbox returned an invalid response envelope.", "INVALID_RESPONSE", response.status_code)
+            return data
+
+        raise ActionboxError("Actionbox request failed after retries.", "RETRY_EXHAUSTED", 0)
+
+    def create(
+        self,
+        *,
+        title: str,
+        description: str = "",
+        options: list[ActionOption] | None = None,
+        interaction: TypedInteraction | None = None,
+        idempotency_key: str | None = None,
+        **payload: Any,
+    ) -> Action:
+        if options is not None and interaction is not None:
+            raise ValueError("provide options or interaction, not both")
+        request_headers = {"Idempotency-Key": idempotency_key or f"sdk-{secrets.token_urlsafe(18)}"}
+        request_payload: dict[str, Any] = {"title": title, "description": description, **payload}
+        if interaction is not None:
+            request_payload["interaction"] = interaction
+        else:
+            request_payload["options"] = options or []
+        data = self._request(
+            "POST",
+            "/v1/actions",
+            json=request_payload,
+            headers=request_headers,
+        )
+        return Action(self, data)
+
+    def get(
+        self,
+        action_id: str,
+        *,
+        wait_seconds: int = 0,
+        cancel_event: threading.Event | None = None,
+    ) -> Action:
+        encoded_id = quote(action_id, safe="")
+        path = f"/v1/source/actions/{encoded_id}"
+        if wait_seconds > 0:
+            path = f"{path}?wait_seconds={min(int(wait_seconds), 30)}"
+        request_timeout = self.timeout
+        if wait_seconds > 0:
+            request_timeout = max(request_timeout, min(wait_seconds, 30) + 5)
+        return Action(
+            self,
+            self._request(
+                "GET",
+                path,
+                cancel_event=cancel_event,
+                timeout=request_timeout,
+            ),
+        )
+
+    def resolve(
+        self,
+        action_id: str,
+        option_id: str | ResolveInput | TypedResponse | None = None,
+        reason: str | None = None,
+        *,
+        response: TypedResponse | None = None,
+        action_version: int | None = None,
+        fingerprint: str | None = None,
+    ) -> Action:
+        if isinstance(option_id, Mapping):
+            generic_input = dict(option_id)
+            if "type" in generic_input and "response" not in generic_input:
+                response = cast(TypedResponse, generic_input)
+                option_id = None
+            else:
+                response = cast(TypedResponse | None, generic_input.get("response", response))
+                reason = cast(str | None, generic_input.get("reason", reason))
+                option_id = cast(str | None, generic_input.get("option_id"))
+            action_version = cast(int | None, generic_input.get("action_version", action_version))
+            fingerprint = cast(str | None, generic_input.get("fingerprint", fingerprint))
+
+        request_payload: dict[str, Any] = {"option_id": option_id, "reason": reason}
+        if action_version is not None:
+            request_payload["action_version"] = action_version
+        if fingerprint is not None:
+            request_payload["fingerprint"] = fingerprint
+        if response is not None:
+            request_payload["response"] = response
+        return Action(
+            self,
+            self._request(
+                "POST",
+                f"/v1/actions/{quote(action_id, safe='')}/resolve",
+                json=request_payload,
+            ),
+        )
+
+    def cancel(self, action_id: str, reason: str | None = None) -> Action:
+        return Action(self, self._request("POST", f"/v1/actions/{quote(action_id, safe='')}/cancel", json={"reason": reason}))
+
+    def report_outcome(
+        self,
+        action_id: str,
+        status: Literal["success", "failed"],
+        *,
+        action_version: int,
+        fingerprint: str,
+        duration_ms: int | None = None,
+        rollback: bool = False,
+        reason_code: str | None = None,
+        cancel_event: threading.Event | None = None,
+    ) -> ActionOutcome:
+        data = self._request(
+            "POST",
+            f"/v1/actions/{quote(action_id, safe='')}/outcome",
+            json={
+                "status": status,
+                "duration_ms": duration_ms,
+                "rollback": rollback,
+                "reason_code": reason_code,
+                "action_version": action_version,
+                "fingerprint": fingerprint,
+            },
+            # Exact outcome replays are idempotent server-side, so transport
+            # retries are safe even if the first response was lost.
+            headers={"Idempotency-Key": f"outcome-{action_id}"},
+            cancel_event=cancel_event,
+        )
+        return cast(ActionOutcome, data)
+
+    def ask(
+        self,
+        *,
+        title: str,
+        options: list[str] | None = None,
+        interaction: TypedInteraction | None = None,
+        wait: bool = True,
+        timeout: float = 3600,
+        poll_interval: float = 2,
+        cancel_event: threading.Event | None = None,
+        **payload: Any,
+    ) -> str | TypedResponse | Action | None:
+        if options is None and interaction is None:
+            raise ValueError("provide options or interaction")
+        if options is not None and interaction is not None:
+            raise ValueError("provide options or interaction, not both")
+        normalized = (
+            [{"id": option.lower().replace(" ", "-"), "label": option} for option in options]
+            if options is not None
+            else None
+        )
+        action = self.create(title=title, options=normalized, interaction=interaction, **payload)
+        return action.wait(timeout=timeout, poll_interval=poll_interval, cancel_event=cancel_event) if wait else action
+
+
+def send_heartbeat(
+    heartbeat_url: str,
+    signal: Literal["ping", "start", "success", "fail"] = "ping",
+    *,
+    timeout: float = 10,
+    cancel_event: threading.Event | None = None,
+) -> None:
+    """Deliver one Watch heartbeat without placing its capability in errors."""
+    _raise_if_cancelled(cancel_event)
+    if timeout <= 0:
+        raise ValueError("timeout must be greater than zero")
+    if signal not in {"ping", "start", "success", "fail"}:
+        raise ValueError("signal must be ping, start, success, or fail")
+    parsed = urlsplit(heartbeat_url.strip())
+    segments = [part for part in parsed.path.split("/") if part]
+    if (
+        len(segments) != 2
+        or segments[0] != "hb"
+        or not segments[1].startswith("hb_")
+        or parsed.username
+        or parsed.password
+        or parsed.query
+        or parsed.fragment
+        or not parsed.hostname
+    ):
+        raise ValueError("heartbeat_url must be an Actionbox heartbeat URL")
+    try:
+        address = ipaddress.ip_address(parsed.hostname)
+        loopback = address.is_loopback
+    except ValueError:
+        loopback = parsed.hostname.casefold() == "localhost"
+    if parsed.scheme != "https" and not (parsed.scheme == "http" and loopback):
+        raise ValueError("heartbeat_url must use HTTPS unless it targets localhost")
+    path = parsed.path if signal == "ping" else f"{parsed.path.rstrip('/')}/{signal}"
+    url = f"{parsed.scheme}://{parsed.netloc}{path}"
+    try:
+        response = httpx.post(url, timeout=timeout)
+    except httpx.HTTPError as exc:
+        raise ActionboxError("Heartbeat delivery failed.", "HEARTBEAT_FAILED", 0) from exc
+    if response.status_code != 204:
+        raise ActionboxError(
+            f"Heartbeat delivery failed with HTTP {response.status_code}.",
+            "HEARTBEAT_FAILED",
+            response.status_code,
+        )
+
+
+def _validate_base_url(value: str) -> str:
+    parsed = urlsplit(value.strip())
+    if not parsed.scheme or not parsed.hostname:
+        raise ValueError("base_url must be a full HTTPS URL")
+    try:
+        address = ipaddress.ip_address(parsed.hostname)
+        loopback = address.is_loopback
+    except ValueError:
+        loopback = parsed.hostname.lower() == "localhost"
+    if parsed.scheme != "https" and not (parsed.scheme == "http" and loopback):
+        raise ValueError("base_url must use HTTPS unless it targets localhost")
+    if parsed.username or parsed.password or parsed.query or parsed.fragment or parsed.path not in {"", "/"}:
+        raise ValueError("base_url must not contain credentials, a path, query parameters, or a fragment")
+    port = f":{parsed.port}" if parsed.port is not None else ""
+    host = f"[{parsed.hostname}]" if ":" in parsed.hostname else parsed.hostname
+    return f"{parsed.scheme}://{host}{port}"
+
+
+def _read_bounded_body(response: httpx.Response) -> bytes:
+    chunks: list[bytes] = []
+    size = 0
+    for chunk in response.iter_bytes():
+        size += len(chunk)
+        if size > _MAX_RESPONSE_BYTES:
+            raise ActionboxError(
+                f"Actionbox response exceeds {_MAX_RESPONSE_BYTES} bytes.",
+                "RESPONSE_TOO_LARGE",
+                response.status_code,
+            )
+        chunks.append(chunk)
+    return b"".join(chunks)
+
+
+def _parse_response_body(raw: bytes, status: int) -> dict[str, Any]:
+    if not raw:
+        return {}
+    try:
+        body = httpx.Response(status, content=raw).json()
+    except ValueError as exc:
+        raise ActionboxError("Actionbox returned invalid JSON.", "INVALID_RESPONSE", status) from exc
+    if not isinstance(body, dict):
+        raise ActionboxError("Actionbox returned an invalid response envelope.", "INVALID_RESPONSE", status)
+    return cast(dict[str, Any], body)
+
+
+def _retry_after_seconds(value: str | None) -> float | None:
+    if not value:
+        return None
+    try:
+        seconds = float(value)
+        return min(max(seconds, 0.0), _MAX_RETRY_DELAY)
+    except ValueError:
+        pass
+    try:
+        timestamp = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if timestamp.tzinfo is None:
+        timestamp = timestamp.replace(tzinfo=UTC)
+    return min(max((timestamp - datetime.now(UTC)).total_seconds(), 0.0), _MAX_RETRY_DELAY)
+
+
+def _raise_if_cancelled(cancel_event: threading.Event | None) -> None:
+    if cancel_event is not None and cancel_event.is_set():
+        raise ActionboxError("Actionbox request was cancelled.", "ABORTED", 0)
+
+
+def _wait_before_retry(
+    attempt: int,
+    retry_after: str | None,
+    cancel_event: threading.Event | None,
+) -> None:
+    server_delay = _retry_after_seconds(retry_after)
+    base = 0.25 * (2**attempt)
+    delay = server_delay if server_delay is not None else base + random.uniform(0, base / 2)
+    if cancel_event is not None:
+        if cancel_event.wait(delay):
+            raise ActionboxError("Actionbox request was cancelled.", "ABORTED", 0)
+    else:
+        time.sleep(delay)
+
+
+__all__ = [
+    "__version__",
+    "Action",
+    "ActionCreateInput",
+    "ActionOption",
+    "ActionOptionInput",
+    "ActionOutcome",
+    "AgentRun",
+    "Actionbox",
+    "ActionboxError",
+    "ActionsResource",
+    "Watch",
+    "WatchCreateInput",
+    "WatchScheduleType",
+    "WatchStatus",
+    "WatchesResource",
+    "BooleanInteraction",
+    "BooleanResponse",
+    "FormBooleanField",
+    "FormField",
+    "FormIntegerField",
+    "FormInteraction",
+    "FormMultiChoiceField",
+    "FormNumberField",
+    "FormResponse",
+    "FormSingleChoiceField",
+    "FormTextField",
+    "IntegerInteraction",
+    "IntegerResponse",
+    "Interaction",
+    "InteractionResponse",
+    "MultiChoiceInteraction",
+    "MultiChoiceResponse",
+    "NumberInteraction",
+    "NumberResponse",
+    "OptionStyle",
+    "ResolveInput",
+    "RunsResource",
+    "RunStatus",
+    "Response",
+    "SingleChoiceInteraction",
+    "SingleChoiceResponse",
+    "TextInteraction",
+    "TextResponse",
+    "TypedInteraction",
+    "TypedResponse",
+    "Watch",
+    "WatchCreateInput",
+    "WatchScheduleType",
+    "WatchStatus",
+    "WatchesResource",
+    "__version__",
+    "send_heartbeat",
+]

actionbox_sdk-0.1.6.dist-info/METADATA

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: actionbox-sdk
+Version: 0.1.6
+Summary: Python client for Actionbox durable human decisions
+License-Expression: MIT
+Project-URL: Documentation, https://actionbox.cloud/docs
+Project-URL: API, https://api.actionbox.cloud/docs
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Dynamic: license-file
+
+<img src="https://actionbox.cloud/appbox.svg" width="64" alt="Actionbox logo">
+
+# Actionbox Python SDK
+
+Actionbox gives backend services a durable, server-authoritative way to ask a
+human for a decision and continue when that decision is available. This package
+is the typed Python client for creating, resolving, and waiting on Actions,
+plus managing source-scoped heartbeat Watches.
+
+## Documentation
+
+- [Actionbox documentation](https://actionbox.cloud/docs)
+
+## Requirements
+
+- Python 3.11 or newer
+- An Actionbox Source API key, supplied through `ACTIONBOX_API_KEY`
+
+Keep API keys and Watch capability URLs on trusted servers, workers, or CI
+jobs. Do not put this SDK or its credentials in browser code.
+
+## Install
+
+```bash
+pip install actionbox-sdk
+```
+
+The distribution is named `actionbox-sdk` so it does not conflict with the
+Actionbox CLI distribution on PyPI. The Python import remains `actionbox`.
+
+```python
+import os
+from actionbox import Actionbox
+
+with Actionbox(os.environ["ACTIONBOX_API_KEY"]) as client:
+    decision = client.ask(
+        title="Deploy to production?",
+        options=["Approve", "Reject"],
+        callback_url="https://ci.example.com/actionbox",
+    )
+    print(decision)
+```
+
+The SDK uses the hosted production API at `https://api.actionbox.cloud` by
+default. Customer integrations should use that default and only pass
+`base_url` in maintainer-controlled test environments.
+
+`ask(..., wait=False)` returns an `Action`; `Action.wait()` polls the server and leaves the Action open when the local timeout expires. The concise single-choice API returns the selected option ID as a string.
+
+## Typed interactions and responses
+
+The SDK exports typed interaction and response contracts that match the REST API. Use an explicit typed interaction with `create` or `ask` when the human response is more than a single choice:
+
+```python
+from actionbox import Actionbox, BooleanInteraction
+
+with Actionbox(os.environ["ACTIONBOX_API_KEY"]) as client:
+    action = client.create(
+        title="Deploy configuration",
+        interaction=BooleanInteraction(
+            type="boolean",
+            label="Deploy now?",
+            true_label="Deploy",
+            false_label="Hold",
+        ),
+    )
+    resolved = client.resolve(
+        action.id,
+        response={"type": "boolean", "value": True},
+        reason="Approved by release manager",
+    )
+    print(resolved.response)  # {"type": "boolean", "value": True}
+```
+
+The available interaction types are `boolean`, `single_choice`, `multi_choice`, `text`, `integer`, `number`, `rating`, and `form`. Form fields use the same typed field shapes and are returned as `{"type": "form", "values": {...}}`. Create inputs also accept bounded developer `context` blocks and an explicit typed `on_expire` fallback; omitting it returns `expired` without inventing a response.
+
+`resolve` supports concise single-choice syntax and generic typed input:
+
+```python
+client.resolve(action.id, "approve")  # single-choice shorthand
+client.resolve(action.id, {"response": {"type": "text", "value": "ship"}})
+client.actions.resolve(action.id, response={"type": "number", "value": 4.5})
+```
+
+`Action.interaction` and `Action.response` expose the canonical typed wire values. `options`, `option_id`, `ask(..., options=[...])`, and string decision results are first-class single-choice conveniences.
+
+## Execution outcomes
+
+After carrying out an approved operation, report its real result from the
+resolved Action snapshot:
+
+```python
+outcome = resolved.report_outcome(
+    "success",
+    duration_ms=48_312,
+    rollback=False,
+)
+```
+
+The SDK sends the Action's exact version and fingerprint. Exact retries are
+safe; Actionbox rejects a conflicting second outcome.
+
+## Agent Runs
+
+Group an agent task and its Actions without managing another framework:
+
+```python
+run = client.runs.start(
+    external_id="checkout-fix-42",
+    agent_name="codex",
+    title="Fix checkout deadlock",
+    stall_after_seconds=900,
+)
+run.progress(stage="tests", checkpoint="test-184")
+action = client.create(title="Approve staging migration", run_id=run.id)
+run.complete()
+```
+
+The SDK handles progress sequence numbers. Runs are optional; standalone
+Actions continue to work exactly as before. When `stall_after_seconds` is set,
+unchanged status/stage/checkpoint updates do not reset the timer. Actionbox
+creates one ordinary Action if progress stalls and resolves it when progress
+changes or the Run completes; `waiting` pauses the timer.
+
+## Heartbeat Watches
+
+Source credentials can create and list Watches scoped to that Source. The raw heartbeat URL is returned only by creation:
+
+```python
+from actionbox import Actionbox, send_heartbeat
+
+with Actionbox(os.environ["ACTIONBOX_API_KEY"]) as client:
+    watch = client.watches.create(
+        source_id="src_…",
+        name="Nightly backup",
+        schedule_type="interval",
+        interval_seconds=3600,
+        grace_seconds=60,
+        signal_method="post",
+    )
+    send_heartbeat(watch.heartbeat_url, "start")
+```
+
+Use `send_heartbeat` for `ping`, `start`, `success`, or `fail`; it always sends
+POST. `signal_method="post"` prevents link previewers and security scanners
+from accidentally recording a heartbeat with GET. The
+source-scoped resource also exposes `client.watches.pause(id)`,
+`resume(id)`, `rotate_token(id)`, and `archive(id)`; only create/rotate return
+a raw URL. Store capability URLs in a secret manager; Watch details and
+exports never return them.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

actionbox_sdk-0.1.6.dist-info/RECORD

@@ -0,0 +1,6 @@
+actionbox/__init__.py,sha256=YNo1ONT4JJHQ0JVH6x5S2KZcGNo2E7wMgQ9dBFefgg8,33096
+actionbox_sdk-0.1.6.dist-info/licenses/LICENSE,sha256=9-tv8G2RZXRAQFiBV4gKdBDMaqUOgNGSM3aoS5SSoEM,1070
+actionbox_sdk-0.1.6.dist-info/METADATA,sha256=8Qy5D9aMW-Fio9macyuB9L2P3GCZF7dm6ayMLXkqU74,5910
+actionbox_sdk-0.1.6.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+actionbox_sdk-0.1.6.dist-info/top_level.txt,sha256=qmZZebCeHoXL38ilOVzKzmA0IcHa_zYbOsgAPbAhZKo,10
+actionbox_sdk-0.1.6.dist-info/RECORD,,

actionbox_sdk-0.1.6.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

actionbox_sdk-0.1.6.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suson Sapkota
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

actionbox_sdk-0.1.6.dist-info/top_level.txt

@@ -0,0 +1 @@
+actionbox