stackshift 0.1.2__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-0.1.2 → stackshift-1.0.1}/README.md

@@ -29,13 +29,13 @@ print(message["id"], message["status"], message["idempotencyStatus"])
 Inspect message status:
 
 ```python
-messages = stackshift.mail.messages.list(status="sent", limit=20)
+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"])
 ```
 
-In this MVP, `sent` means the message was accepted by StackShift's outbound MTA. It does not mean inbox delivery, opens, clicks, or spam placement. A `sent` message can later become `bounced`.
+`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
 

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

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

{stackshift-0.1.2 → stackshift-1.0.1}/stackshift/__init__.py

@@ -8,7 +8,10 @@ from .mail import (
     MailTemplatesClient,
 )
 from .mail_reputation import MailLimitsClient, MailReputationClient, MailReputationEventsClient
-from .mail_phase7 import MailEventsClient, MailWebhooksClient, verify_webhook_signature
+from .mail_events_webhooks import MailEventsClient, MailWebhooksClient, verify_webhook_signature
+from .mail_streams import MailStreamsClient
+from .mail_campaigns import MailAudiencesClient, MailCampaignsClient
+from .mail_exports import MailExportsClient
 from .projects import ProjectsClient
 
 __all__ = [
@@ -25,6 +28,10 @@ __all__ = [
     "MailReputationEventsClient",
     "MailTemplatesClient",
     "MailWebhooksClient",
+    "MailStreamsClient",
+    "MailAudiencesClient",
+    "MailCampaignsClient",
+    "MailExportsClient",
     "ProjectsClient",
     "asset_transform_options",
     "asset_transform_spec",

{stackshift-0.1.2 → 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-0.1.2 → stackshift-1.0.1}/stackshift/client.py

@@ -43,7 +43,7 @@ class StackShift:
     def _request(self, base_url: str, method: str, path: str, **kwargs: Any) -> Any:
         headers = kwargs.pop("headers", {})
         headers["Authorization"] = f"Bearer {self.api_key}"
-        headers["User-Agent"] = "StackShift-Python/0.1"
+        headers["User-Agent"] = "StackShift-Python/1.0"
 
         response = self.session.request(method, f"{base_url}{path}", headers=headers, **kwargs)
         payload = response.json() if response.content else None

{stackshift-0.1.2 → stackshift-1.0.1}/stackshift/mail.py

@@ -4,8 +4,11 @@ from typing import Any
 from urllib.parse import quote
 
 from .mail_advanced import MailAnalyticsClient, MailBatchClient, MailInboundClient, MailScheduledClient
-from .mail_phase7 import MailEventsClient, MailWebhooksClient
+from .mail_events_webhooks import MailEventsClient, MailWebhooksClient
 from .mail_reputation import MailLimitsClient, MailReputationClient
+from .mail_streams import MailStreamsClient
+from .mail_campaigns import MailAudiencesClient, MailCampaignsClient
+from .mail_exports import MailExportsClient
 
 
 class MailClient:
@@ -19,6 +22,10 @@ class MailClient:
         self.templates = MailTemplatesClient(client)
         self.events = MailEventsClient(client)
         self.webhooks = MailWebhooksClient(client)
+        self.streams = MailStreamsClient(client)
+        self.audiences = MailAudiencesClient(client)
+        self.campaigns = MailCampaignsClient(client)
+        self.exports = MailExportsClient(client)
         self.limits = MailLimitsClient(client)
         self.reputation = MailReputationClient(client)
         self.scheduled = MailScheduledClient(client)
@@ -39,6 +46,9 @@ class MailClient:
         reply_to: str | dict[str, str] | None = None,
         idempotency_key: str | None = None,
         attachments: list[dict[str, Any]] | None = None,
+        headers: dict[str, str] | None = None,
+        tags: dict[str, str] | None = None,
+        stream: str | None = None,
     ) -> dict[str, Any]:
         payload = {
             "from": from_,
@@ -51,6 +61,9 @@ class MailClient:
             "text": text,
             "idempotencyKey": idempotency_key,
             "attachments": attachments,
+            "headers": headers,
+            "tags": tags,
+            "stream": stream,
         }
         clean = {key: value for key, value in payload.items() if value is not None}
         return self._client.mail_request("POST", "/mail/send", json=clean)
@@ -68,6 +81,9 @@ class MailClient:
         reply_to: str | dict[str, str] | None = None,
         idempotency_key: str | None = None,
         attachments: list[dict[str, Any]] | None = None,
+        headers: dict[str, str] | None = None,
+        tags: dict[str, str] | None = None,
+        stream: str | None = None,
     ) -> dict[str, Any]:
         payload = {
             "template": template,
@@ -80,6 +96,9 @@ class MailClient:
             "data": data,
             "idempotencyKey": idempotency_key,
             "attachments": attachments,
+            "headers": headers,
+            "tags": tags,
+            "stream": stream,
         }
         clean = {key: value for key, value in payload.items() if value is not None}
         return self._client.mail_request("POST", "/mail/send-template", json=clean)
@@ -162,6 +181,18 @@ class MailTemplatesClient:
         clean = {key: value for key, value in payload.items() if value is not None}
         return self._client.mail_request("POST", f"/mail/templates/{quote(template_id)}/preview", json=clean)
 
+    def diagnostics(
+        self,
+        template_id: str,
+        *,
+        data: dict[str, Any] | None = None,
+        version_id: str | None = None,
+        stream: str | None = None,
+    ) -> dict[str, Any]:
+        payload = {"data": data, "versionId": version_id, "stream": stream}
+        clean = {key: value for key, value in payload.items() if value is not None}
+        return self._client.mail_request("POST", f"/mail/templates/{quote(template_id)}/diagnostics", json=clean)
+
     def test_send(
         self,
         template_id: str,
@@ -231,8 +262,9 @@ class MailMessagesClient:
     def bounces(self, message_id: str) -> dict[str, Any]:
         return self._client.mail_request("GET", f"/mail/messages/{quote(message_id)}/bounces")
 
-    def timeline(self, message_id: str) -> dict[str, Any]:
-        return self._client.mail_request("GET", f"/mail/messages/{quote(message_id)}/timeline")
+    def timeline(self, message_id: str, *, recipient: str | None = None) -> dict[str, Any]:
+        params = {"recipient": recipient} if recipient else None
+        return self._client.mail_request("GET", f"/mail/messages/{quote(message_id)}/timeline", params=params)
 
 
 class MailSuppressionsClient:

{stackshift-0.1.2 → stackshift-1.0.1}/stackshift/mail_advanced.py

@@ -36,11 +36,31 @@ class MailBatchClient:
         from_: str | dict[str, str],
         recipients: list[dict[str, Any]],
         version_id: str | None = None,
+        headers: dict[str, str] | None = None,
+        tags: dict[str, str] | None = None,
+        stream: str | None = None,
     ) -> dict[str, Any]:
-        payload = {"template": template, "from": from_, "recipients": recipients, "versionId": version_id}
+        payload = {
+            "template": template,
+            "from": from_,
+            "recipients": recipients,
+            "versionId": version_id,
+            "headers": headers,
+            "tags": tags,
+            "stream": stream,
+        }
         clean = {key: value for key, value in payload.items() if value is not None}
         return self._client.mail_request("POST", "/mail/batch-template", json=clean)
 
+    def list(self) -> dict[str, Any]:
+        return self._client.mail_request("GET", "/mail/batches")
+
+    def get(self, batch_id: str) -> dict[str, Any]:
+        return self._client.mail_request("GET", f"/mail/batches/{quote(batch_id)}")
+
+    def items(self, batch_id: str) -> dict[str, Any]:
+        return self._client.mail_request("GET", f"/mail/batches/{quote(batch_id)}/items")
+
 
 class MailInboundClient:
     def __init__(self, client: Any) -> None:

stackshift-1.0.1/stackshift/mail_campaigns.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+
+class MailAudiencesClient:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def create(self, *, name: str, description: str | None = None) -> dict[str, Any]:
+        payload = {"name": name, "description": description}
+        return self._client.mail_request("POST", "/mail/audiences", json={key: value for key, value in payload.items() if value is not None})
+
+    def list(self) -> dict[str, Any]:
+        return self._client.mail_request("GET", "/mail/audiences")
+
+    def get(self, audience_id: str) -> dict[str, Any]:
+        return self._client.mail_request("GET", f"/mail/audiences/{quote(audience_id)}")
+
+    def members(self, audience_id: str) -> dict[str, Any]:
+        return self._client.mail_request("GET", f"/mail/audiences/{quote(audience_id)}/members")
+
+    def import_members(self, audience_id: str, members: list[dict[str, Any]]) -> dict[str, Any]:
+        return self._client.mail_request(
+            "POST",
+            f"/mail/audiences/{quote(audience_id)}/imports",
+            json={"members": members},
+        )
+
+
+class MailCampaignsClient:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def create(
+        self,
+        *,
+        name: str,
+        audience_id: str,
+        template: str,
+        from_: str,
+        version_id: str | None = None,
+    ) -> dict[str, Any]:
+        payload = {
+            "name": name,
+            "audienceId": audience_id,
+            "template": template,
+            "from": from_,
+            "versionId": version_id,
+        }
+        return self._client.mail_request("POST", "/mail/campaigns", json={key: value for key, value in payload.items() if value is not None})
+
+    def list(self) -> dict[str, Any]:
+        return self._client.mail_request("GET", "/mail/campaigns")
+
+    def get(self, campaign_id: str) -> dict[str, Any]:
+        return self._client.mail_request("GET", f"/mail/campaigns/{quote(campaign_id)}")
+
+    def send(self, campaign_id: str) -> dict[str, Any]:
+        return self._client.mail_request("POST", f"/mail/campaigns/{quote(campaign_id)}/send")

stackshift-0.1.2/stackshift/mail_phase7.py → stackshift-1.0.1/stackshift/mail_events_webhooks.py

@@ -100,6 +100,14 @@ class MailWebhooksClient:
     def retry_delivery(self, delivery_id: str) -> dict[str, Any]:
         return self._client.mail_request("POST", f"/mail/webhook-deliveries/{quote(delivery_id)}/retry")
 
+    def replay(self, webhook_id: str, *, event_ids: list[str], idempotency_key: str) -> dict[str, Any]:
+        return self._client.mail_request(
+            "POST",
+            f"/mail/webhooks/{quote(webhook_id)}/replay",
+            headers={"Idempotency-Key": idempotency_key},
+            json={"eventIds": event_ids},
+        )
+
     def verify_signature(
         self,
         *,

stackshift-1.0.1/stackshift/mail_exports.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+from urllib.parse import quote
+
+
+class MailExportsClient:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def create(self, *, from_: datetime | None = None, to: datetime | None = None) -> dict[str, Any]:
+        payload = {
+            "kind": "recipient_delivery",
+            "format": "jsonl",
+            "from": from_.isoformat() if from_ else None,
+            "to": to.isoformat() if to else None,
+        }
+        return self._client.mail_request(
+            "POST", "/mail/exports", json={key: value for key, value in payload.items() if value is not None}
+        )
+
+    def list(self) -> dict[str, Any]:
+        return self._client.mail_request("GET", "/mail/exports")
+
+    def get(self, export_id: str) -> dict[str, Any]:
+        return self._client.mail_request("GET", f"/mail/exports/{quote(export_id)}")
+
+    def download_path(self, export_id: str) -> str:
+        return f"/mail/exports/{quote(export_id)}/download"

stackshift-1.0.1/stackshift/mail_streams.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class MailStreamsClient:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def create(self, *, name: str, slug: str, type: str) -> dict[str, Any]:
+        return self._client.mail_request(
+            "POST",
+            "/mail/streams",
+            json={"name": name, "slug": slug, "type": type},
+        )
+
+    def list(self) -> dict[str, Any]:
+        return self._client.mail_request("GET", "/mail/streams")

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-0.1.2 → stackshift-1.0.1}/stackshift.egg-info/SOURCES.txt

@@ -2,17 +2,24 @@ README.md
 pyproject.toml
 stackshift/__init__.py
 stackshift/assets.py
+stackshift/assets_workflows.py
 stackshift/client.py
 stackshift/mail.py
 stackshift/mail_advanced.py
-stackshift/mail_phase7.py
+stackshift/mail_campaigns.py
+stackshift/mail_events_webhooks.py
+stackshift/mail_exports.py
 stackshift/mail_reputation.py
+stackshift/mail_streams.py
 stackshift/projects.py
 stackshift.egg-info/PKG-INFO
 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_phase7.py
+tests/test_mail_diagnostics.py
+tests/test_mail_events_webhooks.py
+tests/test_mail_exports.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-0.1.2 → stackshift-1.0.1}/tests/test_mail.py

@@ -96,9 +96,9 @@ class FakeSession:
         if url.endswith("/mail/bounces"):
             return FakeResponse(200, {"data": [bounce_response()], "nextCursor": None})
         if url.endswith("/mail/messages/msg_123"):
-            return FakeResponse(200, {"id": "msg_123", "from": {"email": "noreply@mail.stackshift.cloud"}, "to": ["ada@example.com"], "cc": [], "bcc": [], "subject": "Welcome", "status": "sent"})
+            return FakeResponse(200, {"id": "msg_123", "from": {"email": "noreply@mail.stackshift.cloud"}, "to": ["ada@example.com"], "cc": [], "bcc": [], "subject": "Welcome", "status": "mta_accepted"})
         if url.endswith("/mail/messages"):
-            return FakeResponse(200, {"data": [{"id": "msg_123", "status": "sent"}], "nextCursor": None})
+            return FakeResponse(200, {"data": [{"id": "msg_123", "status": "mta_accepted"}], "nextCursor": None})
         if url.endswith("/assets/transformations") and method == "GET":
             return FakeResponse(200, {"success": True, "data": {"transformations": [{"id": "tr_1", "name": "custom-card", "normalized_spec": "w_640,h_360,c_fill,f_webp,q_82"}]}})
         if url.endswith("/assets/transformations") and method == "POST":
@@ -152,12 +152,12 @@ class MailSDKTest(unittest.TestCase):
         self.assertEqual(session.calls[0][1], "https://api.stackshift.cloud/v1/mail/send")
         self.assertEqual(session.calls[0][2]["headers"]["Authorization"], "Bearer sk_test")
 
-        messages = stackshift.mail.messages.list(status="sent", limit=20)
-        self.assertEqual(messages["data"][0]["status"], "sent")
-        self.assertEqual(session.calls[1][2]["params"]["status"], "sent")
+        messages = stackshift.mail.messages.list(status="mta_accepted", limit=20)
+        self.assertEqual(messages["data"][0]["status"], "mta_accepted")
+        self.assertEqual(session.calls[1][2]["params"]["status"], "mta_accepted")
 
         message = stackshift.mail.messages.get("msg_123")
-        self.assertEqual(message["status"], "sent")
+        self.assertEqual(message["status"], "mta_accepted")
 
         attempts = stackshift.mail.messages.attempts("msg_123")
         self.assertEqual(attempts["data"][0]["status"], "accepted_by_mta")
@@ -312,7 +312,7 @@ def domain_response(status):
             {
                 "type": "TXT",
                 "name": "acme.com",
-                "value": "v=spf1 include:_spf.stackshift.email ~all",
+                "value": "v=spf1 include:_spf.stackshift.cloud ~all",
                 "status": "verified",
                 "required": True,
             }

{stackshift-0.1.2 → stackshift-1.0.1}/tests/test_mail_advanced.py

@@ -39,6 +39,12 @@ class FakeSession:
             return FakeResponse(202, {"id": "batch_tpl_123", "status": "queued", "messageCount": 1})
         if url.endswith("/mail/batch"):
             return FakeResponse(202, {"id": "batch_123", "status": "queued", "messageCount": 1})
+        if url.endswith("/mail/batches/batch_123/items"):
+            return FakeResponse(200, {"data": [{"id": "item_123", "recipients": [{"email": "ada@example.com", "status": "delivered"}]}]})
+        if url.endswith("/mail/batches/batch_123"):
+            return FakeResponse(200, {"id": "batch_123", "status": "completed", "messageCount": 1})
+        if url.endswith("/mail/batches"):
+            return FakeResponse(200, {"data": [{"id": "batch_123", "status": "completed", "messageCount": 1}]})
         if url.endswith("/mail/inbound/domains") and method == "POST":
             return FakeResponse(201, {"id": "ind_123", "domain": "inbound.example.com", "status": "pending"})
         if url.endswith("/mail/inbound/domains"):
@@ -50,7 +56,7 @@ class FakeSession:
         if url.endswith("/mail/inbound/messages"):
             return FakeResponse(200, {"data": [{"id": "inm_123", "fromEmail": "ada@example.com", "toEmails": ["support@example.com"]}]})
         if url.endswith("/mail/analytics"):
-            return FakeResponse(200, {"summary": {"sent": 1}, "series": [{"bucket": "2026-05-11", "sent": 1}]})
+            return FakeResponse(200, {"summary": {"mtaAccepted": 1}, "series": [{"bucket": "2026-05-11", "mtaAccepted": 1}]})
         return FakeResponse(404, {"error": {"code": "not_found", "message": "Not found."}})
 
 
@@ -80,6 +86,9 @@ class MailAdvancedSDKTest(unittest.TestCase):
             recipients=[{"to": "ada@example.com", "data": {"name": "Ada"}}],
         )
         self.assertEqual(template_batch["id"], "batch_tpl_123")
+        self.assertEqual(stackshift.mail.batch.list()["data"][0]["id"], "batch_123")
+        self.assertEqual(stackshift.mail.batch.get("batch_123")["status"], "completed")
+        self.assertEqual(stackshift.mail.batch.items("batch_123")["data"][0]["recipients"][0]["status"], "delivered")
 
         self.assertEqual(stackshift.mail.inbound.domains.create("inbound.example.com")["id"], "ind_123")
         self.assertEqual(stackshift.mail.inbound.domains.list()["data"][0]["status"], "verified")
@@ -88,7 +97,7 @@ class MailAdvancedSDKTest(unittest.TestCase):
         self.assertEqual(stackshift.mail.inbound.messages.get("inm_123")["fromEmail"], "ada@example.com")
 
         analytics = stackshift.mail.analytics.get(range_="7d", interval="day", domain="example.com")
-        self.assertEqual(analytics["summary"]["sent"], 1)
+        self.assertEqual(analytics["summary"]["mtaAccepted"], 1)
         self.assertEqual(session.calls[-1][2]["params"]["domain"], "example.com")
 
 

stackshift-1.0.1/tests/test_mail_diagnostics.py

@@ -0,0 +1,22 @@
+import unittest
+
+from stackshift.mail import MailTemplatesClient
+
+
+class FakeClient:
+    def __init__(self):
+        self.calls = []
+
+    def mail_request(self, method, path, **kwargs):
+        self.calls.append((method, path, kwargs))
+        return {"status": "warning", "findings": [{"code": "remote_images"}]}
+
+
+class MailDiagnosticsTest(unittest.TestCase):
+    def test_template_diagnostics(self):
+        raw = FakeClient()
+        result = MailTemplatesClient(raw).diagnostics("tpl_123", stream="broadcast")
+
+        self.assertEqual(result["findings"][0]["code"], "remote_images")
+        self.assertEqual(raw.calls[0][0:2], ("POST", "/mail/templates/tpl_123/diagnostics"))
+        self.assertEqual(raw.calls[0][2]["json"]["stream"], "broadcast")

stackshift-0.1.2/tests/test_mail_phase7.py → stackshift-1.0.1/tests/test_mail_events_webhooks.py

@@ -34,7 +34,7 @@ class FakeSession:
         if url.endswith("/mail/events/evt_123"):
             return FakeResponse(200, event_response())
         if url.endswith("/mail/messages/msg_123/timeline"):
-            return FakeResponse(200, {"data": [{"type": "mail.message.sent", "label": "Accepted by StackShift outbound MTA"}]})
+            return FakeResponse(200, {"data": [{"type": "mail.message.mta_accepted", "label": "Accepted by StackShift outbound MTA"}]})
         if url.endswith("/mail/webhooks") and method == "POST":
             payload = webhook_response()
             payload["secret"] = "whsec_test"
@@ -60,22 +60,22 @@ class FakeSession:
         return FakeResponse(404, {"error": {"code": "not_found", "message": "Not found."}})
 
 
-class MailPhase7SDKTest(unittest.TestCase):
+class MailEventsWebhooksSDKTest(unittest.TestCase):
     def test_events_timeline_and_webhooks(self):
         session = FakeSession()
         stackshift = StackShift(api_key="sk_test", session=session)
 
-        events = stackshift.mail.events.list(type="mail.message.sent", message_id="msg_123", limit=20)
+        events = stackshift.mail.events.list(type="mail.message.mta_accepted", message_id="msg_123", limit=20)
         self.assertEqual(events["data"][0]["id"], "evt_123")
         self.assertEqual(session.calls[0][2]["params"]["messageId"], "msg_123")
 
         event = stackshift.mail.events.get("evt_123")
-        self.assertEqual(event["type"], "mail.message.sent")
+        self.assertEqual(event["type"], "mail.message.mta_accepted")
 
         timeline = stackshift.mail.messages.timeline("msg_123")
         self.assertEqual(timeline["data"][0]["label"], "Accepted by StackShift outbound MTA")
 
-        created = stackshift.mail.webhooks.create(url="https://example.com/hook", event_types=["mail.message.sent"])
+        created = stackshift.mail.webhooks.create(url="https://example.com/hook", event_types=["mail.message.mta_accepted"])
         self.assertEqual(created["secret"], "whsec_test")
 
         webhooks = stackshift.mail.webhooks.list(limit=10)
@@ -140,9 +140,9 @@ class MailPhase7SDKTest(unittest.TestCase):
 def event_response():
     return {
         "id": "evt_123",
-        "type": "mail.message.sent",
+        "type": "mail.message.mta_accepted",
         "messageId": "msg_123",
-        "payload": {"messageId": "msg_123", "status": "sent"},
+        "payload": {"messageId": "msg_123", "status": "mta_accepted"},
         "occurredAt": "2026-05-09T12:00:00Z",
         "createdAt": "2026-05-09T12:00:00Z",
     }
@@ -154,7 +154,7 @@ def webhook_response():
         "url": "https://example.com/hook",
         "description": None,
         "status": "active",
-        "eventTypes": ["mail.message.sent"],
+        "eventTypes": ["mail.message.mta_accepted"],
         "createdAt": "2026-05-09T12:00:00Z",
     }
 

stackshift-1.0.1/tests/test_mail_exports.py

@@ -0,0 +1,30 @@
+import unittest
+from datetime import datetime, timezone
+
+from stackshift.mail_exports import MailExportsClient
+
+
+class FakeClient:
+    def __init__(self):
+        self.calls = []
+
+    def mail_request(self, method, path, **kwargs):
+        self.calls.append((method, path, kwargs))
+        return {"id": "exp_123", "status": "queued"}
+
+
+class MailExportsTest(unittest.TestCase):
+    def test_create_list_get_and_download_path(self):
+        raw = FakeClient()
+        exports = MailExportsClient(raw)
+        created = exports.create(from_=datetime(2026, 8, 1, tzinfo=timezone.utc))
+        exports.list()
+        exports.get("exp_123")
+
+        self.assertEqual(created["id"], "exp_123")
+        self.assertEqual(raw.calls[0][2]["json"]["kind"], "recipient_delivery")
+        self.assertEqual(exports.download_path("exp_123"), "/mail/exports/exp_123/download")
+
+
+if __name__ == "__main__":
+    unittest.main()

stackshift-0.1.2/PKG-INFO

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

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

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