stackshift 1.0.0__tar.gz → 1.0.1__tar.gz

stackshift-1.0.1/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: stackshift
+Version: 1.0.1
+Summary: Official Python SDK for StackShift.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31
+
+# StackShift Python SDK
+
+Official Python SDK for StackShift.
+
+## Install
+
+```bash
+pip install stackshift
+```
+
+## Send email
+
+```python
+from stackshift import StackShift
+
+stackshift = StackShift()
+
+message = stackshift.mail.send(
+    from_="StackShift <noreply@mail.stackshift.cloud>",
+    to="ada@example.com",
+    subject="Welcome",
+    text="Welcome to StackShift.",
+    idempotency_key="welcome:user_123",
+)
+
+print(message["id"], message["status"], message["idempotencyStatus"])
+```
+
+Inspect message status:
+
+```python
+messages = stackshift.mail.messages.list(status="mta_accepted", limit=20)
+detail = stackshift.mail.messages.get(messages["data"][0]["id"])
+attempts = stackshift.mail.messages.attempts(detail["id"])
+logs = stackshift.mail.messages.logs(detail["id"])
+```
+
+`mta_accepted` means the message was accepted by StackShift's outbound MTA. It does not mean recipient-MX acceptance, inbox placement, opens, clicks, or spam placement. Recipient records later transition independently to `delayed`, `delivered`, `bounced`, `failed`, `suppressed`, or `complained`.
+
+## Events and webhooks
+
+```python
+events = stackshift.mail.events.list(
+    type="mail.message.bounced",
+    message_id="msg_123",
+    limit=20,
+)
+
+event = stackshift.mail.events.get("evt_123")
+timeline = stackshift.mail.messages.timeline("msg_123")
+
+webhook = stackshift.mail.webhooks.create(
+    url="https://example.com/stackshift-mail",
+    event_types=["mail.message.bounced", "mail.otp.verified"],
+)
+print(webhook["id"], webhook["secret"])  # Secret is only returned on create/rotate.
+
+deliveries = stackshift.mail.webhooks.deliveries(webhook["id"], status="failed")
+retried = stackshift.mail.webhooks.retry_delivery(deliveries["data"][0]["id"])
+```
+
+Verify a webhook signature before processing the payload:
+
+```python
+valid = stackshift.mail.webhooks.verify_signature(
+    raw_body=request.get_data(),
+    signature_header=request.headers.get("StackShift-Signature"),
+    timestamp_header=request.headers.get("StackShift-Timestamp"),
+    secret=os.environ["STACKSHIFT_WEBHOOK_SECRET"],
+)
+```
+
+Webhook handlers should be idempotent. StackShift retries non-2xx responses. Delivery events do not include full email bodies or OTP codes by default.
+
+## Send a template
+
+Templates are rendered by StackShift servers. The Python SDK only calls the REST API.
+
+```python
+stackshift.mail.templates.create(
+    name="Welcome Email",
+    slug="welcome-email",
+    subject="Welcome, {{name}}",
+    text="Welcome, {{name}}",
+)
+
+preview = stackshift.mail.templates.preview(
+    "welcome-email",
+    data={"name": "Ada"},
+)
+
+message = stackshift.mail.send_template(
+    template="welcome-email",
+    to="ada@example.com",
+    from_="Acme <noreply@acme.com>",
+    data={"name": "Ada"},
+    idempotency_key="welcome:user_123",
+)
+```
+
+Missing variables fail before a message is queued. Template sends use the same sender-domain, suppression, idempotency, Durable Jobs, and Postfix handoff pipeline as `mail.send`.
+
+## Bounces and suppressions
+
+```python
+suppressions = stackshift.mail.suppressions.list()
+
+manual = stackshift.mail.suppressions.create(
+    email="bad@example.com",
+    reason="manual",
+)
+
+stackshift.mail.suppressions.delete(manual["id"])
+
+bounces = stackshift.mail.bounces.list(type="hard")
+message_bounces = stackshift.mail.messages.bounces("msg_123")
+```
+
+Hard bounces are automatically suppressed by the backend. Suppressions are workspace scoped and checked before a message is queued.
+
+## Verify a sending domain
+
+```python
+domain = stackshift.mail.domains.create("acme.com")
+print(domain["records"])
+
+stackshift.mail.domains.verify(domain["id"])
+
+message = stackshift.mail.send(
+    from_="Acme <noreply@acme.com>",
+    to="user@example.com",
+    subject="Welcome",
+    html="<h1>Welcome</h1>",
+    text="Welcome",
+)
+```
+
+Add the returned SPF, DKIM, and return-path DNS records before verification. DMARC is recommended unless your environment sets `MAIL_DMARC_REQUIRED=true`. DNS propagation can take time.
+
+## Upload an asset
+
+```python
+from stackshift import StackShift
+
+stackshift = StackShift()
+
+asset = stackshift.assets.upload(
+    "avatar.png",
+    folder="avatars",
+    visibility="public",
+    metadata={"user_id": "user_123"},
+)
+
+print(asset["url"])
+```
+
+You do not pass a deployed StackShift project ID. The API key identifies the StackShift account, and StackShift resolves the default asset space internally.
+
+## Private asset URL
+
+```python
+signed = stackshift.assets.signed_url(
+    asset["id"],
+    expires_in="10m",
+    max_downloads=1,
+)
+
+print(signed["url"])
+```
+
+## Image transformations
+
+Use built-in presets or create your own named transformations.
+
+```python
+from stackshift import StackShift, asset_transform_options, get_asset_transform_preset
+
+stackshift = StackShift()
+hero = get_asset_transform_preset("hero")
+hero_options = asset_transform_options(hero)
+
+stackshift.assets.create_transformation(hero["name"], **hero_options)
+
+named = stackshift.assets.named_url("asset_123", hero["name"])
+signed = stackshift.assets.signed_transform_url("asset_123", **hero_options, expiresIn="10m")
+
+stackshift.assets.delete_transformation("old-preset")
+print(named, signed["url"])
+```
+
+## Direct browser uploads
+
+Create the upload session on your Python backend:
+
+```python
+upload = stackshift.assets.signed_upload_url(
+    bucket="avatars",
+    key="users/user_123.png",
+    visibility="public",
+    expiresIn="10m",
+    maxBytes=5_000_000,
+)
+```
+
+Then upload the browser `File` to `upload["url"]` from your frontend. Do not expose your StackShift API key to browser code.
+
+The SDK only talks to the StackShift REST API. Storage placement, replication, disks, and repair are StackShift internals.

{stackshift-1.0.0 → stackshift-1.0.1}/pyproject.toml

@@ -4,8 +4,9 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stackshift"
-version = "1.0.0"
+version = "1.0.1"
 description = "Official Python SDK for StackShift."
+readme = "README.md"
 requires-python = ">=3.9"
 dependencies = ["requests>=2.31"]
 

{stackshift-1.0.0 → stackshift-1.0.1}/stackshift/assets.py

@@ -6,6 +6,8 @@ from pathlib import Path
 from typing import Any, BinaryIO
 from urllib.parse import quote
 
+from .assets_workflows import AssetWorkflowsMixin
+
 
 ASSET_TRANSFORM_PRESETS: list[dict[str, Any]] = [
     {"id": "web-thumbnail", "name": "web-thumbnail", "category": "responsive-web", "description": "Compact grid thumbnail for libraries and dashboards.", "width": 320, "height": 180, "crop": "fill", "format": "webp", "quality": 78},
@@ -47,7 +49,7 @@ def asset_transform_spec(**options: Any) -> str:
     return _transform_spec(options)
 
 
-class AssetsClient:
+class AssetsClient(AssetWorkflowsMixin):
     def __init__(self, client: Any) -> None:
         self._client = client
 

stackshift-1.0.1/stackshift/assets_workflows.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote, urlencode
+
+
+class AssetWorkflowsMixin:
+    """Typed route helpers for deterministic media and governed asset workflows."""
+
+    _client: Any
+
+    def create_transformation_v2(
+        self, name: str, definition: dict[str, Any], *, eager: bool = False
+    ) -> dict[str, Any]:
+        return self._client.request(
+            "POST", "/assets/transformations",
+            json={"name": name, "definition": definition, "eager": eager},
+        )
+
+    def materialize_transform(
+        self,
+        asset_id: str,
+        *,
+        definition: dict[str, Any] | None = None,
+        preset: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        payload = {key: value for key, value in {
+            "definition": definition, "preset": preset,
+        }.items() if value not in (None, "")}
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self._client.request(
+            "POST", f"/assets/{quote(asset_id, safe='')}/transforms", json=payload, headers=headers
+        )
+
+    def derivatives(self, asset_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/assets/{quote(asset_id, safe='')}/derivatives")
+
+    def generate(
+        self, payload: dict[str, Any], *, idempotency_key: str
+    ) -> dict[str, Any]:
+        return self._client.request(
+            "POST", "/assets/generations", json=payload,
+            headers={"Idempotency-Key": idempotency_key},
+        )
+
+    def automation(self) -> dict[str, Any]:
+        return self._client.request("GET", "/assets/automation")
+
+    def workflow_catalog(self) -> dict[str, Any]:
+        return self._client.request("GET", "/assets/workflows/catalog")
+
+    def create_workflow(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request("POST", "/assets/workflows", json=payload)
+
+    def workflows(self, *, page: int = 1, per_page: int = 20) -> list[dict[str, Any]]:
+        query = urlencode({"page": page, "per_page": per_page})
+        return self._client.request("GET", f"/assets/workflows?{query}")
+
+    def workflow(self, workflow_id: str) -> dict[str, Any]:
+        return self._client.request("GET", self._workflow_path(workflow_id))
+
+    def update_workflow_draft(
+        self, workflow_id: str, payload: dict[str, Any]
+    ) -> dict[str, Any]:
+        return self._client.request(
+            "PUT", f"{self._workflow_path(workflow_id)}/draft", json=payload
+        )
+
+    def validate_workflow(self, workflow_id: str) -> dict[str, Any]:
+        return self._client.request("POST", f"{self._workflow_path(workflow_id)}/validate")
+
+    def publish_workflow(
+        self, workflow_id: str, expected_revision: int
+    ) -> dict[str, Any]:
+        return self._client.request(
+            "POST", f"{self._workflow_path(workflow_id)}/publish",
+            json={"expected_revision": expected_revision},
+        )
+
+    def activate_workflow(
+        self, workflow_id: str, version_id: str, expected_revision: int
+    ) -> None:
+        self._client.request(
+            "POST", f"{self._workflow_path(workflow_id)}/activate",
+            json={"version_id": version_id, "expected_revision": expected_revision},
+        )
+
+    def workflow_versions(self, workflow_id: str) -> list[dict[str, Any]]:
+        return self._client.request("GET", f"{self._workflow_path(workflow_id)}/versions")
+
+    def run_workflow(
+        self, workflow_id: str, payload: dict[str, Any] | None = None,
+        *, idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self._client.request(
+            "POST", f"{self._workflow_path(workflow_id)}/run",
+            json=payload or {}, headers=headers,
+        )
+
+    def workflow_runs(
+        self, workflow_id: str, *, page: int = 1, per_page: int = 20
+    ) -> list[dict[str, Any]]:
+        query = urlencode({"page": page, "per_page": per_page})
+        return self._client.request(
+            "GET", f"{self._workflow_path(workflow_id)}/runs?{query}"
+        )
+
+    def workflow_run(self, run_id: str) -> dict[str, Any]:
+        return self._client.request("GET", self._workflow_run_path(run_id))
+
+    def cancel_workflow_run(self, run_id: str) -> dict[str, Any]:
+        return self._client.request("POST", f"{self._workflow_run_path(run_id)}/cancel")
+
+    def retry_workflow_run(self, run_id: str) -> dict[str, Any]:
+        return self._client.request("POST", f"{self._workflow_run_path(run_id)}/retry")
+
+    def workflow_approvals(self, status: str | None = None) -> list[dict[str, Any]]:
+        if status:
+            return self._client.request(
+                "GET", f"/assets/workflows/approvals?{urlencode({'status': status})}"
+            )
+        return self._client.request("GET", "/assets/workflows/approvals")
+
+    def decide_workflow_approval(
+        self, approval_id: str, approved: bool, payload: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        return (
+            self.approve_workflow(approval_id, payload)
+            if approved else self.reject_workflow(approval_id, payload)
+        )
+
+    def approve_workflow(
+        self, approval_id: str, payload: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        return self._client.request(
+            "POST", f"/assets/workflows/approvals/{quote(approval_id, safe='')}/approve",
+            json=payload or {},
+        )
+
+    def reject_workflow(
+        self, approval_id: str, payload: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        return self._client.request(
+            "POST", f"/assets/workflows/approvals/{quote(approval_id, safe='')}/reject",
+            json=payload or {},
+        )
+
+    def workflow_connections(self) -> list[dict[str, Any]]:
+        return self._client.request("GET", "/assets/workflows/connections")
+
+    def create_workflow_connection(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request("POST", "/assets/workflows/connections", json=payload)
+
+    def rotate_workflow_connection_credential(
+        self, connection_id: str, payload: dict[str, Any]
+    ) -> dict[str, Any]:
+        return self._client.request(
+            "POST",
+            f"/assets/workflows/connections/{quote(connection_id, safe='')}/credential/rotate",
+            json=payload,
+        )
+
+    def rotate_workflow_inbound_hook(self, workflow_id: str) -> dict[str, Any]:
+        return self._client.request(
+            "POST", f"{self._workflow_path(workflow_id)}/inbound-hook/rotate"
+        )
+
+    @staticmethod
+    def _workflow_path(workflow_id: str) -> str:
+        return f"/assets/workflows/{quote(workflow_id, safe='')}"
+
+    @staticmethod
+    def _workflow_run_path(run_id: str) -> str:
+        return f"/assets/workflows/runs/{quote(run_id, safe='')}"

stackshift-1.0.1/stackshift.egg-info/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: stackshift
+Version: 1.0.1
+Summary: Official Python SDK for StackShift.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31
+
+# StackShift Python SDK
+
+Official Python SDK for StackShift.
+
+## Install
+
+```bash
+pip install stackshift
+```
+
+## Send email
+
+```python
+from stackshift import StackShift
+
+stackshift = StackShift()
+
+message = stackshift.mail.send(
+    from_="StackShift <noreply@mail.stackshift.cloud>",
+    to="ada@example.com",
+    subject="Welcome",
+    text="Welcome to StackShift.",
+    idempotency_key="welcome:user_123",
+)
+
+print(message["id"], message["status"], message["idempotencyStatus"])
+```
+
+Inspect message status:
+
+```python
+messages = stackshift.mail.messages.list(status="mta_accepted", limit=20)
+detail = stackshift.mail.messages.get(messages["data"][0]["id"])
+attempts = stackshift.mail.messages.attempts(detail["id"])
+logs = stackshift.mail.messages.logs(detail["id"])
+```
+
+`mta_accepted` means the message was accepted by StackShift's outbound MTA. It does not mean recipient-MX acceptance, inbox placement, opens, clicks, or spam placement. Recipient records later transition independently to `delayed`, `delivered`, `bounced`, `failed`, `suppressed`, or `complained`.
+
+## Events and webhooks
+
+```python
+events = stackshift.mail.events.list(
+    type="mail.message.bounced",
+    message_id="msg_123",
+    limit=20,
+)
+
+event = stackshift.mail.events.get("evt_123")
+timeline = stackshift.mail.messages.timeline("msg_123")
+
+webhook = stackshift.mail.webhooks.create(
+    url="https://example.com/stackshift-mail",
+    event_types=["mail.message.bounced", "mail.otp.verified"],
+)
+print(webhook["id"], webhook["secret"])  # Secret is only returned on create/rotate.
+
+deliveries = stackshift.mail.webhooks.deliveries(webhook["id"], status="failed")
+retried = stackshift.mail.webhooks.retry_delivery(deliveries["data"][0]["id"])
+```
+
+Verify a webhook signature before processing the payload:
+
+```python
+valid = stackshift.mail.webhooks.verify_signature(
+    raw_body=request.get_data(),
+    signature_header=request.headers.get("StackShift-Signature"),
+    timestamp_header=request.headers.get("StackShift-Timestamp"),
+    secret=os.environ["STACKSHIFT_WEBHOOK_SECRET"],
+)
+```
+
+Webhook handlers should be idempotent. StackShift retries non-2xx responses. Delivery events do not include full email bodies or OTP codes by default.
+
+## Send a template
+
+Templates are rendered by StackShift servers. The Python SDK only calls the REST API.
+
+```python
+stackshift.mail.templates.create(
+    name="Welcome Email",
+    slug="welcome-email",
+    subject="Welcome, {{name}}",
+    text="Welcome, {{name}}",
+)
+
+preview = stackshift.mail.templates.preview(
+    "welcome-email",
+    data={"name": "Ada"},
+)
+
+message = stackshift.mail.send_template(
+    template="welcome-email",
+    to="ada@example.com",
+    from_="Acme <noreply@acme.com>",
+    data={"name": "Ada"},
+    idempotency_key="welcome:user_123",
+)
+```
+
+Missing variables fail before a message is queued. Template sends use the same sender-domain, suppression, idempotency, Durable Jobs, and Postfix handoff pipeline as `mail.send`.
+
+## Bounces and suppressions
+
+```python
+suppressions = stackshift.mail.suppressions.list()
+
+manual = stackshift.mail.suppressions.create(
+    email="bad@example.com",
+    reason="manual",
+)
+
+stackshift.mail.suppressions.delete(manual["id"])
+
+bounces = stackshift.mail.bounces.list(type="hard")
+message_bounces = stackshift.mail.messages.bounces("msg_123")
+```
+
+Hard bounces are automatically suppressed by the backend. Suppressions are workspace scoped and checked before a message is queued.
+
+## Verify a sending domain
+
+```python
+domain = stackshift.mail.domains.create("acme.com")
+print(domain["records"])
+
+stackshift.mail.domains.verify(domain["id"])
+
+message = stackshift.mail.send(
+    from_="Acme <noreply@acme.com>",
+    to="user@example.com",
+    subject="Welcome",
+    html="<h1>Welcome</h1>",
+    text="Welcome",
+)
+```
+
+Add the returned SPF, DKIM, and return-path DNS records before verification. DMARC is recommended unless your environment sets `MAIL_DMARC_REQUIRED=true`. DNS propagation can take time.
+
+## Upload an asset
+
+```python
+from stackshift import StackShift
+
+stackshift = StackShift()
+
+asset = stackshift.assets.upload(
+    "avatar.png",
+    folder="avatars",
+    visibility="public",
+    metadata={"user_id": "user_123"},
+)
+
+print(asset["url"])
+```
+
+You do not pass a deployed StackShift project ID. The API key identifies the StackShift account, and StackShift resolves the default asset space internally.
+
+## Private asset URL
+
+```python
+signed = stackshift.assets.signed_url(
+    asset["id"],
+    expires_in="10m",
+    max_downloads=1,
+)
+
+print(signed["url"])
+```
+
+## Image transformations
+
+Use built-in presets or create your own named transformations.
+
+```python
+from stackshift import StackShift, asset_transform_options, get_asset_transform_preset
+
+stackshift = StackShift()
+hero = get_asset_transform_preset("hero")
+hero_options = asset_transform_options(hero)
+
+stackshift.assets.create_transformation(hero["name"], **hero_options)
+
+named = stackshift.assets.named_url("asset_123", hero["name"])
+signed = stackshift.assets.signed_transform_url("asset_123", **hero_options, expiresIn="10m")
+
+stackshift.assets.delete_transformation("old-preset")
+print(named, signed["url"])
+```
+
+## Direct browser uploads
+
+Create the upload session on your Python backend:
+
+```python
+upload = stackshift.assets.signed_upload_url(
+    bucket="avatars",
+    key="users/user_123.png",
+    visibility="public",
+    expiresIn="10m",
+    maxBytes=5_000_000,
+)
+```
+
+Then upload the browser `File` to `upload["url"]` from your frontend. Do not expose your StackShift API key to browser code.
+
+The SDK only talks to the StackShift REST API. Storage placement, replication, disks, and repair are StackShift internals.

{stackshift-1.0.0 → stackshift-1.0.1}/stackshift.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ README.md
 pyproject.toml
 stackshift/__init__.py
 stackshift/assets.py
+stackshift/assets_workflows.py
 stackshift/client.py
 stackshift/mail.py
 stackshift/mail_advanced.py
@@ -16,6 +17,7 @@ stackshift.egg-info/SOURCES.txt
 stackshift.egg-info/dependency_links.txt
 stackshift.egg-info/requires.txt
 stackshift.egg-info/top_level.txt
+tests/test_assets_workflows.py
 tests/test_mail.py
 tests/test_mail_advanced.py
 tests/test_mail_diagnostics.py

stackshift-1.0.1/tests/test_assets_workflows.py

@@ -0,0 +1,34 @@
+from stackshift.assets import AssetsClient
+
+
+class FakeClient:
+    def __init__(self):
+        self.calls = []
+
+    def request(self, method, path, **kwargs):
+        self.calls.append((method, path, kwargs))
+        return {"method": method, "path": path}
+
+
+def test_transform_generation_and_workflow_routes():
+    transport = FakeClient()
+    assets = AssetsClient(transport)
+
+    assets.materialize_transform(
+        "asset/1", preset="web-ready", idempotency_key="render-1"
+    )
+    method, path, options = transport.calls[-1]
+    assert (method, path) == ("POST", "/assets/asset%2F1/transforms")
+    assert options["json"] == {"preset": "web-ready"}
+    assert options["headers"]["Idempotency-Key"] == "render-1"
+
+    assets.generate(
+        {"prompt": "A violet nebula", "size": "1024x1024", "format": "png", "bucket": "generated"},
+        idempotency_key="generation-1",
+    )
+    assert transport.calls[-1][2]["headers"]["Idempotency-Key"] == "generation-1"
+
+    assets.publish_workflow("workflow/1", 4)
+    method, path, options = transport.calls[-1]
+    assert (method, path) == ("POST", "/assets/workflows/workflow%2F1/publish")
+    assert options["json"] == {"expected_revision": 4}

stackshift-1.0.0/PKG-INFO

@@ -1,6 +0,0 @@
-Metadata-Version: 2.4
-Name: stackshift
-Version: 1.0.0
-Summary: Official Python SDK for StackShift.
-Requires-Python: >=3.9
-Requires-Dist: requests>=2.31

stackshift-1.0.0/stackshift.egg-info/PKG-INFO

@@ -1,6 +0,0 @@
-Metadata-Version: 2.4
-Name: stackshift
-Version: 1.0.0
-Summary: Official Python SDK for StackShift.
-Requires-Python: >=3.9
-Requires-Dist: requests>=2.31