actionbox 0.1.2__tar.gz

actionbox-0.1.2/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-0.1.2/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: actionbox
+Version: 0.1.2
+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
+Project-URL: Source, https://github.com/susonsapkota/actionbox
+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
+```
+
+```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.
+
+## 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,
+    )
+    send_heartbeat(watch.heartbeat_url, "start")
+```
+
+Use `send_heartbeat` for `ping`, `start`, `success`, or `fail`. 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.
+
+## Release and versioning
+
+The Node and Python SDKs are released together from signed `sdk-vMAJOR.MINOR.PATCH`
+tags. The release workflow derives the package versions from the tag, runs both
+test suites, and publishes the packages only after the tag and publishing
+environments pass their checks.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

actionbox-0.1.2/README.md

@@ -0,0 +1,117 @@
+<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
+```
+
+```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.
+
+## 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,
+    )
+    send_heartbeat(watch.heartbeat_url, "start")
+```
+
+Use `send_heartbeat` for `ping`, `start`, `success`, or `fail`. 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.
+
+## Release and versioning
+
+The Node and Python SDKs are released together from signed `sdk-vMAJOR.MINOR.PATCH`
+tags. The release workflow derives the package versions from the tag, runs both
+test suites, and publishes the packages only after the tag and publishing
+environments pass their checks.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).