stackshift 1.2.0__tar.gz → 1.3.0__tar.gz

{stackshift-1.2.0 → stackshift-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackshift
-Version: 1.2.0
+Version: 1.3.0
 Summary: Official Python SDK for StackShift.
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -101,6 +101,35 @@ valid = stackshift.mail.webhooks.verify_signature(
 
 Webhook handlers should be idempotent. StackShift retries non-2xx responses. Delivery events do not include full email bodies or OTP codes by default.
 
+## Mailboxes
+
+Host real mailboxes on your own domain. The mailbox owner gets an invitation by email and sets their own password.
+
+```python
+domain = stackshift.mail.mailbox_domains.create("acme.com")
+print(domain["records"])
+stackshift.mail.mailbox_domains.verify(domain["id"])
+
+mailbox = stackshift.mail.mailboxes.create(
+    domain_id=domain["id"],
+    local_part="ada",
+    owner_email="ada@personal.example",
+    plan="basic",
+)
+
+stackshift.mail.aliases.create(mailbox_id=mailbox["id"], local_part="sales", send_as=True)
+stackshift.mail.routes.create(
+    domain_id=domain["id"],
+    pattern="orders-*",
+    targets=[{"kind": "app", "webhookUrl": "https://app.example.com/inbound"}],
+)
+
+devices = stackshift.mail.mailboxes.list_devices(mailbox["id"])
+stackshift.mail.mailboxes.suspend(mailbox["id"])
+```
+
+`stackshift.mail.groups` manages team addresses, and `stackshift.mail.mailbox_imports` copies mail from Google, Microsoft or any IMAP server.
+
 ## Send a template
 
 Templates are rendered by StackShift servers. The Python SDK only calls the REST API.
@@ -282,3 +311,20 @@ preview = platform.migrations.start({"source_connection_id": connection_id,
     "destination_bucket_id": bucket_id, "source_prefix": "campaigns/2026", "dry_run": True})
 report = platform.migrations.report(preview["id"])
 ```
+
+## Support action receivers (unreleased)
+
+`ActionManifest`, `ActionDescriptor`, installation consent types and `validate_action_catalog` describe `stackshift.support.app/v2`. V1 remains actionless. Registered writes require idempotency, a reconciliation endpoint and a registered read verifier; installations explicitly select `action_operations`. These SDK helpers perform no registration or network calls.
+
+Use `receive_action(raw_bytes, headers, store=..., execute=..., reconcile=..., verification=...)`. Verification requires `key_id`, `secret` (the installation action secret, not webhook secret), `installation_id`, `actions`, and a trusted `expected_customer_external_id`. Do not derive that expectation from unverified request JSON. Each synchronous handler returns `(state, result_dict, optional_safe_error_code)`. Success output is checked against the registered flat schema. Receipt helpers `encode_receipt`, `sign_action`, and `verify_receipt` are also exported.
+
+`SQLiteActionStore('/absolute/path/claims.sqlite')` uses standard-library sqlite3, WAL and FULL synchronization. Never use an in-memory database for restart safety. The runnable stdin receiver in `examples/support_action_receiver.py` intentionally returns `demo_not_implemented`; replace its handlers with authorized customer-bound business transactions. Set `ACTION_KEY_ID`, `ACTION_SECRET`, `ACTION_INSTALLATION_ID`, and trusted `EXPECTED_CUSTOMER_EXTERNAL_ID`:
+
+```sh
+PYTHONPATH=. python examples/support_action_receiver.py /absolute/path/claims.sqlite headers.json actions.json < body.json
+.venv/bin/python -m unittest discover -s tests -p test_support_actions.py -v
+```
+
+Send the returned `body` unchanged with `headers`. Execution retries retain exact original bytes and request ID with fresh delivery IDs. A handler error is stored as unknown; running/unknown work is never dispatched again. Reconciliation is a separate handler with empty arguments and the original target request ID, and must query actual downstream state. Accepted results remain replayable; there is no asynchronous callback endpoint yet. Disk claims do not make remote side effects atomic: use downstream idempotency or one transactional business/receipt store, and preserve uncertain claims for reconciliation/human review. This is a single-host SQLite example; distributed receivers need a shared durable store.
+
+See `../support-actions-conformance/README.md` for exact signatures and adapter requirements. Seven action tests pass, including shared vectors, two-connection concurrency, restart and fenced completion. The existing virtualenv is required here because system Python lacks the SDK's declared `requests` dependency. No live installation/provider qualification was performed; unreleased.

{stackshift-1.2.0 → stackshift-1.3.0}/README.md

@@ -93,6 +93,35 @@ valid = stackshift.mail.webhooks.verify_signature(
 
 Webhook handlers should be idempotent. StackShift retries non-2xx responses. Delivery events do not include full email bodies or OTP codes by default.
 
+## Mailboxes
+
+Host real mailboxes on your own domain. The mailbox owner gets an invitation by email and sets their own password.
+
+```python
+domain = stackshift.mail.mailbox_domains.create("acme.com")
+print(domain["records"])
+stackshift.mail.mailbox_domains.verify(domain["id"])
+
+mailbox = stackshift.mail.mailboxes.create(
+    domain_id=domain["id"],
+    local_part="ada",
+    owner_email="ada@personal.example",
+    plan="basic",
+)
+
+stackshift.mail.aliases.create(mailbox_id=mailbox["id"], local_part="sales", send_as=True)
+stackshift.mail.routes.create(
+    domain_id=domain["id"],
+    pattern="orders-*",
+    targets=[{"kind": "app", "webhookUrl": "https://app.example.com/inbound"}],
+)
+
+devices = stackshift.mail.mailboxes.list_devices(mailbox["id"])
+stackshift.mail.mailboxes.suspend(mailbox["id"])
+```
+
+`stackshift.mail.groups` manages team addresses, and `stackshift.mail.mailbox_imports` copies mail from Google, Microsoft or any IMAP server.
+
 ## Send a template
 
 Templates are rendered by StackShift servers. The Python SDK only calls the REST API.
@@ -274,3 +303,20 @@ preview = platform.migrations.start({"source_connection_id": connection_id,
     "destination_bucket_id": bucket_id, "source_prefix": "campaigns/2026", "dry_run": True})
 report = platform.migrations.report(preview["id"])
 ```
+
+## Support action receivers (unreleased)
+
+`ActionManifest`, `ActionDescriptor`, installation consent types and `validate_action_catalog` describe `stackshift.support.app/v2`. V1 remains actionless. Registered writes require idempotency, a reconciliation endpoint and a registered read verifier; installations explicitly select `action_operations`. These SDK helpers perform no registration or network calls.
+
+Use `receive_action(raw_bytes, headers, store=..., execute=..., reconcile=..., verification=...)`. Verification requires `key_id`, `secret` (the installation action secret, not webhook secret), `installation_id`, `actions`, and a trusted `expected_customer_external_id`. Do not derive that expectation from unverified request JSON. Each synchronous handler returns `(state, result_dict, optional_safe_error_code)`. Success output is checked against the registered flat schema. Receipt helpers `encode_receipt`, `sign_action`, and `verify_receipt` are also exported.
+
+`SQLiteActionStore('/absolute/path/claims.sqlite')` uses standard-library sqlite3, WAL and FULL synchronization. Never use an in-memory database for restart safety. The runnable stdin receiver in `examples/support_action_receiver.py` intentionally returns `demo_not_implemented`; replace its handlers with authorized customer-bound business transactions. Set `ACTION_KEY_ID`, `ACTION_SECRET`, `ACTION_INSTALLATION_ID`, and trusted `EXPECTED_CUSTOMER_EXTERNAL_ID`:
+
+```sh
+PYTHONPATH=. python examples/support_action_receiver.py /absolute/path/claims.sqlite headers.json actions.json < body.json
+.venv/bin/python -m unittest discover -s tests -p test_support_actions.py -v
+```
+
+Send the returned `body` unchanged with `headers`. Execution retries retain exact original bytes and request ID with fresh delivery IDs. A handler error is stored as unknown; running/unknown work is never dispatched again. Reconciliation is a separate handler with empty arguments and the original target request ID, and must query actual downstream state. Accepted results remain replayable; there is no asynchronous callback endpoint yet. Disk claims do not make remote side effects atomic: use downstream idempotency or one transactional business/receipt store, and preserve uncertain claims for reconciliation/human review. This is a single-host SQLite example; distributed receivers need a shared durable store.
+
+See `../support-actions-conformance/README.md` for exact signatures and adapter requirements. Seven action tests pass, including shared vectors, two-connection concurrency, restart and fenced completion. The existing virtualenv is required here because system Python lacks the SDK's declared `requests` dependency. No live installation/provider qualification was performed; unreleased.

{stackshift-1.2.0 → stackshift-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stackshift"
-version = "1.2.0"
+version = "1.3.0"
 description = "Official Python SDK for StackShift."
 readme = "README.md"
 requires-python = ">=3.9"

{stackshift-1.2.0 → stackshift-1.3.0}/stackshift/__init__.py

@@ -13,6 +13,14 @@ from .mail_events_webhooks import MailEventsClient, MailWebhooksClient, verify_w
 from .mail_streams import MailStreamsClient
 from .mail_campaigns import MailAudiencesClient, MailCampaignsClient
 from .mail_exports import MailExportsClient
+from .mail_mailboxes import (
+    MailboxAliasesClient,
+    MailboxDomainsClient,
+    MailboxGroupsClient,
+    MailboxImportsClient,
+    MailboxesClient,
+    MailboxRoutesClient,
+)
 from .projects import ProjectsClient
 from .workload_security import WorkloadSecurityClient
 
@@ -35,6 +43,12 @@ __all__ = [
     "MailAudiencesClient",
     "MailCampaignsClient",
     "MailExportsClient",
+    "MailboxAliasesClient",
+    "MailboxDomainsClient",
+    "MailboxGroupsClient",
+    "MailboxImportsClient",
+    "MailboxesClient",
+    "MailboxRoutesClient",
     "ProjectsClient",
     "WorkloadSecurityClient",
     "asset_transform_options",
@@ -42,3 +56,13 @@ __all__ = [
     "get_asset_transform_preset",
     "verify_webhook_signature",
 ]
+
+from .support_actions import (ActionProtocolError, sign_action, verify_action, verify_receipt, encode_receipt)
+from .support_action_receiver import ActionClaim, ActionDurableStore, SignedActionResponse, receive_action
+from .support_action_sqlite import SQLiteActionStore
+from .support_action_types import ActionDescriptor, ActionField, ActionManifest, ActionRequest, ActionReceipt
+__all__ += ["ActionProtocolError", "sign_action", "verify_action", "verify_receipt", "encode_receipt", "ActionClaim", "ActionDurableStore", "SignedActionResponse", "receive_action", "SQLiteActionStore", "ActionDescriptor", "ActionField", "ActionManifest", "ActionRequest", "ActionReceipt"]
+from .support_action_manifest import validate_action_catalog
+__all__ += ['validate_action_catalog']
+from .support_action_types import ActionInstallationInput, ActionInstallationCredentials
+__all__ += ['ActionInstallationInput', 'ActionInstallationCredentials']

{stackshift-1.2.0 → stackshift-1.3.0}/stackshift/client.py

@@ -12,7 +12,7 @@ class StackShift:
         *,
         api_key: str | None = None,
         base_url: str = "https://api.stackshift.cloud/api/v1",
-        mail_base_url: str = "https://api.stackshift.cloud/v1",
+        mail_base_url: str = "https://api.stackshift.cloud/api/v1",
         cdn_base_url: str = "https://cdn.stackshift.cloud",
         session: requests.Session | None = None,
     ) -> None:

{stackshift-1.2.0 → stackshift-1.3.0}/stackshift/mail.py

@@ -13,6 +13,14 @@ from .mail_marketing import MailAutomationsClient, MailFormsClient, MailSegments
 from .mail_migration import MailMigrationClient
 from .mail_campaigns import MailAudiencesClient, MailCampaignsClient
 from .mail_exports import MailExportsClient
+from .mail_mailboxes import (
+    MailboxAliasesClient,
+    MailboxDomainsClient,
+    MailboxGroupsClient,
+    MailboxImportsClient,
+    MailboxesClient,
+    MailboxRoutesClient,
+)
 from .mail_tracking import MailTrackingClient
 
 
@@ -38,6 +46,12 @@ class MailClient:
         self.campaigns = MailCampaignsClient(client)
         self.tracking = MailTrackingClient(client)
         self.exports = MailExportsClient(client)
+        self.mailbox_domains = MailboxDomainsClient(client)
+        self.mailboxes = MailboxesClient(client)
+        self.aliases = MailboxAliasesClient(client)
+        self.groups = MailboxGroupsClient(client)
+        self.routes = MailboxRoutesClient(client)
+        self.mailbox_imports = MailboxImportsClient(client)
         self.limits = MailLimitsClient(client)
         self.reputation = MailReputationClient(client)
         self.scheduled = MailScheduledClient(client)

{stackshift-1.2.0 → stackshift-1.3.0}/stackshift/mail_campaigns.py

@@ -58,8 +58,8 @@ class MailCampaignsClient:
     def create(
         self,
         *,
-        name: str,
         audience_id: str,
+        name: str | None = None,
         template: str = "",
         from_: str = "",
         version_id: str | None = None,

stackshift-1.3.0/stackshift/mail_mailboxes.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+
+def _seg(value: str) -> str:
+    return quote(value, safe="")
+
+
+def _camel(fields: dict[str, Any], names: dict[str, str], label: str) -> dict[str, Any]:
+    unknown = fields.keys() - names.keys() - set(names.values())
+    if unknown:
+        raise ValueError(f"Unknown {label} fields: " + ", ".join(sorted(unknown)))
+    return {names.get(key, key): value for key, value in fields.items()}
+
+
+def _present(payload: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in payload.items() if value is not None}
+
+
+class MailboxDomainsClient:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def create(self, domain: str) -> dict[str, Any]:
+        return self._client.mail_request("POST", "/mail/mailbox-domains", json={"domain": domain})
+
+    def list(self) -> dict[str, Any]:
+        return self._client.mail_request("GET", "/mail/mailbox-domains")
+
+    def get(self, domain_id: str) -> dict[str, Any]:
+        return self._client.mail_request("GET", f"/mail/mailbox-domains/{_seg(domain_id)}")
+
+    def update(self, domain_id: str, **fields: Any) -> dict[str, Any]:
+        names = {"catch_all": "catchAll", "retention_days": "retentionDays", "addon_storage_units": "addonStorageUnits"}
+        return self._client.mail_request(
+            "PATCH", f"/mail/mailbox-domains/{_seg(domain_id)}", json=_camel(fields, names, "mailbox domain")
+        )
+
+    def verify(self, domain_id: str) -> dict[str, Any]:
+        return self._client.mail_request("POST", f"/mail/mailbox-domains/{_seg(domain_id)}/verify")
+
+    def apply_dns(self, domain_id: str) -> dict[str, Any]:
+        return self._client.mail_request("POST", f"/mail/mailbox-domains/{_seg(domain_id)}/dns/apply")
+
+    def dns_applications(self, domain_id: str) -> dict[str, Any]:
+        return self._client.mail_request("GET", f"/mail/mailbox-domains/{_seg(domain_id)}/dns/applications")
+
+    def delete(self, domain_id: str) -> None:
+        self._client.mail_request("DELETE", f"/mail/mailbox-domains/{_seg(domain_id)}")
+
+
+class MailboxesClient:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def plans(self) -> dict[str, Any]:
+        return self._client.mail_request("GET", "/mail/mailbox-plans")
+
+    def client_settings(self) -> dict[str, Any]:
+        return self._client.mail_request("GET", "/mail/mailbox-client-settings")
+
+    def usage(self) -> dict[str, Any]:
+        return self._client.mail_request("GET", "/mail/mailbox-usage")
+
+    def create(
+        self,
+        *,
+        domain_id: str,
+        local_part: str,
+        display_name: str | None = None,
+        kind: str | None = None,
+        owner_user_id: str | None = None,
+        owner_email: str | None = None,
+        plan: str | None = None,
+        quota_bytes: int | None = None,
+        ai_enabled: bool | None = None,
+    ) -> dict[str, Any]:
+        payload = {
+            "domainId": domain_id,
+            "localPart": local_part,
+            "displayName": display_name,
+            "kind": kind,
+            "ownerUserId": owner_user_id,
+            "ownerEmail": owner_email,
+            "plan": plan,
+            "quotaBytes": quota_bytes,
+            "aiEnabled": ai_enabled,
+        }
+        return self._client.mail_request("POST", "/mail/mailboxes", json=_present(payload))
+
+    def list(self, *, domain_id: str | None = None) -> dict[str, Any]:
+        return self._client.mail_request("GET", "/mail/mailboxes", params=_present({"domainId": domain_id}))
+
+    def get(self, mailbox_id: str) -> dict[str, Any]:
+        return self._client.mail_request("GET", f"/mail/mailboxes/{_seg(mailbox_id)}")
+
+    def update(
+        self,
+        mailbox_id: str,
+        *,
+        display_name: str | None = None,
+        quota_bytes: int | None = None,
+        ai_enabled: bool | None = None,
+        plan: str | None = None,
+    ) -> dict[str, Any]:
+        payload = {"displayName": display_name, "quotaBytes": quota_bytes, "aiEnabled": ai_enabled, "plan": plan}
+        return self._client.mail_request("PATCH", f"/mail/mailboxes/{_seg(mailbox_id)}", json=_present(payload))
+
+    def delete(self, mailbox_id: str) -> None:
+        self._client.mail_request("DELETE", f"/mail/mailboxes/{_seg(mailbox_id)}")
+
+    def suspend(self, mailbox_id: str) -> dict[str, Any]:
+        return self._client.mail_request("POST", f"/mail/mailboxes/{_seg(mailbox_id)}/suspend")
+
+    def resume(self, mailbox_id: str) -> dict[str, Any]:
+        return self._client.mail_request("POST", f"/mail/mailboxes/{_seg(mailbox_id)}/resume")
+
+    def resend_invitation(self, mailbox_id: str) -> dict[str, Any]:
+        return self._client.mail_request("POST", f"/mail/mailboxes/{_seg(mailbox_id)}/invitation/resend")
+
+    def reset_password(self, mailbox_id: str) -> dict[str, Any]:
+        return self._client.mail_request("POST", f"/mail/mailboxes/{_seg(mailbox_id)}/password-reset")
+
+    def create_profile_link(self, mailbox_id: str) -> dict[str, Any]:
+        return self._client.mail_request("POST", f"/mail/mailboxes/{_seg(mailbox_id)}/mobileconfig")
+
+    def list_devices(self, mailbox_id: str) -> dict[str, Any]:
+        return self._client.mail_request("GET", f"/mail/mailboxes/{_seg(mailbox_id)}/devices")
+
+    def revoke_device(self, mailbox_id: str, kind: str, device_id: str) -> None:
+        self._client.mail_request("DELETE", f"/mail/mailboxes/{_seg(mailbox_id)}/devices/{_seg(kind)}/{_seg(device_id)}")
+
+    def list_members(self, mailbox_id: str) -> dict[str, Any]:
+        return self._client.mail_request("GET", f"/mail/mailboxes/{_seg(mailbox_id)}/members")
+
+    def add_member(self, mailbox_id: str, user_id: str) -> dict[str, Any]:
+        return self._client.mail_request("POST", f"/mail/mailboxes/{_seg(mailbox_id)}/members", json={"userId": user_id})
+
+    def remove_member(self, mailbox_id: str, user_id: str) -> None:
+        self._client.mail_request("DELETE", f"/mail/mailboxes/{_seg(mailbox_id)}/members/{_seg(user_id)}")
+
+    def list_app_passwords(self, mailbox_id: str) -> dict[str, Any]:
+        return self._client.mail_request("GET", f"/mail/mailboxes/{_seg(mailbox_id)}/app-passwords")
+
+    def create_app_password(self, mailbox_id: str, label: str) -> dict[str, Any]:
+        return self._client.mail_request(
+            "POST", f"/mail/mailboxes/{_seg(mailbox_id)}/app-passwords", json={"label": label}
+        )
+
+    def revoke_app_password(self, mailbox_id: str, password_id: str) -> None:
+        self._client.mail_request("DELETE", f"/mail/mailboxes/{_seg(mailbox_id)}/app-passwords/{_seg(password_id)}")
+
+
+class MailboxAliasesClient:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def create(
+        self, *, mailbox_id: str, local_part: str, domain_id: str | None = None, send_as: bool | None = None
+    ) -> dict[str, Any]:
+        payload = {"mailboxId": mailbox_id, "localPart": local_part, "domainId": domain_id, "sendAs": send_as}
+        return self._client.mail_request("POST", "/mail/aliases", json=_present(payload))
+
+    def list(self, *, mailbox_id: str | None = None) -> dict[str, Any]:
+        return self._client.mail_request("GET", "/mail/aliases", params=_present({"mailboxId": mailbox_id}))
+
+    def update(self, alias_id: str, *, send_as: bool) -> dict[str, Any]:
+        return self._client.mail_request("PATCH", f"/mail/aliases/{_seg(alias_id)}", json={"sendAs": send_as})
+
+    def delete(self, alias_id: str) -> None:
+        self._client.mail_request("DELETE", f"/mail/aliases/{_seg(alias_id)}")
+
+
+class MailboxGroupsClient:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def create(
+        self,
+        *,
+        domain_id: str,
+        local_part: str,
+        display_name: str | None = None,
+        member_ids: list[str] | None = None,
+        moderator_id: str | None = None,
+    ) -> dict[str, Any]:
+        payload = {
+            "domainId": domain_id,
+            "localPart": local_part,
+            "displayName": display_name,
+            "memberIds": member_ids,
+            "moderatorId": moderator_id,
+        }
+        return self._client.mail_request("POST", "/mail/groups", json=_present(payload))
+
+    def list(self, *, domain_id: str | None = None) -> dict[str, Any]:
+        return self._client.mail_request("GET", "/mail/groups", params=_present({"domainId": domain_id}))
+
+    def get(self, group_id: str) -> dict[str, Any]:
+        return self._client.mail_request("GET", f"/mail/groups/{_seg(group_id)}")
+
+    def update(self, group_id: str, **fields: Any) -> dict[str, Any]:
+        names = {"display_name": "displayName", "moderator_id": "moderatorId", "member_ids": "memberIds"}
+        return self._client.mail_request("PATCH", f"/mail/groups/{_seg(group_id)}", json=_camel(fields, names, "group"))
+
+    def delete(self, group_id: str) -> None:
+        self._client.mail_request("DELETE", f"/mail/groups/{_seg(group_id)}")
+
+
+class MailboxRoutesClient:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def create(
+        self, *, domain_id: str, pattern: str, targets: list[dict[str, Any]], priority: int | None = None
+    ) -> dict[str, Any]:
+        payload = {"domainId": domain_id, "pattern": pattern, "targets": targets, "priority": priority}
+        return self._client.mail_request("POST", "/mail/routes", json=_present(payload))
+
+    def list(self, *, domain_id: str | None = None) -> dict[str, Any]:
+        return self._client.mail_request("GET", "/mail/routes", params=_present({"domainId": domain_id}))
+
+    def get(self, route_id: str) -> dict[str, Any]:
+        return self._client.mail_request("GET", f"/mail/routes/{_seg(route_id)}")
+
+    def update(
+        self, route_id: str, *, priority: int | None = None, targets: list[dict[str, Any]] | None = None
+    ) -> dict[str, Any]:
+        return self._client.mail_request(
+            "PATCH", f"/mail/routes/{_seg(route_id)}", json=_present({"priority": priority, "targets": targets})
+        )
+
+    def delete(self, route_id: str) -> None:
+        self._client.mail_request("DELETE", f"/mail/routes/{_seg(route_id)}")
+
+    def app_health(self, domain_id: str) -> dict[str, Any]:
+        return self._client.mail_request("GET", "/mail/routes/app-health", params={"domainId": domain_id})
+
+    def retry_deliveries(self, route_id: str) -> dict[str, Any]:
+        return self._client.mail_request("POST", f"/mail/routes/{_seg(route_id)}/retry-deliveries")
+
+
+class MailboxImportsClient:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def start(
+        self,
+        *,
+        domain_id: str,
+        source: str,
+        accounts: list[dict[str, Any]],
+        host: str | None = None,
+        port: int | None = None,
+    ) -> dict[str, Any]:
+        payload = {"domainId": domain_id, "source": source, "accounts": accounts, "host": host, "port": port}
+        return self._client.mail_request("POST", "/mail/mailbox-imports", json=_present(payload))
+
+    def list(self) -> dict[str, Any]:
+        return self._client.mail_request("GET", "/mail/mailbox-imports")
+
+    def get(self, import_id: str) -> dict[str, Any]:
+        return self._client.mail_request("GET", f"/mail/mailbox-imports/{_seg(import_id)}")
+
+    def cancel(self, import_id: str) -> dict[str, Any]:
+        return self._client.mail_request("POST", f"/mail/mailbox-imports/{_seg(import_id)}/cancel")
+
+    def skip(self, import_id: str, mailbox_id: str) -> dict[str, Any]:
+        return self._client.mail_request(
+            "POST", f"/mail/mailbox-imports/{_seg(import_id)}/mailboxes/{_seg(mailbox_id)}/skip"
+        )
+
+    def switch(self, import_id: str, when: str) -> dict[str, Any]:
+        return self._client.mail_request("POST", f"/mail/mailbox-imports/{_seg(import_id)}/switch", json={"when": when})

stackshift-1.3.0/stackshift/support_action_manifest.py

@@ -0,0 +1,40 @@
+"""Local catalog validation; server registration and destination policy remain authoritative."""
+import math
+import re
+from urllib.parse import urlsplit
+from .support_actions import _check
+
+_RESERVED = {'customer', 'customer_id', 'external_customer_id', 'external_id', 'contact_id', 'workspace_id', 'environment_id', 'inbox_id', 'conversation_id', 'installation_id', 'tenant_id', 'user_id', 'organization_id', 'authorization', 'scope', 'identity', 'credentials', 'secret', 'token'}
+def _endpoint(value):
+    if not isinstance(value, str) or len(value) > 2048: return False
+    try:
+        url = urlsplit(value)
+        return url.scheme == 'https' and bool(url.hostname) and not url.username and not url.password and '?' not in value and '#' not in value
+    except ValueError: return False
+
+def _fields(schema, input_schema):
+    _check(type(schema) is dict and len(schema) <= 32, 'invalid_catalog')
+    for name, field in schema.items():
+        _check(bool(re.fullmatch(r'[a-z][a-z0-9_]{0,63}', name)) and (not input_schema or name not in _RESERVED and not name.startswith(('customer_', 'tenant_', 'auth_'))), 'invalid_catalog')
+        _check(type(field) is dict and {'type', 'required'} <= field.keys() and field.keys() <= {'type', 'required', 'max_length', 'minimum', 'maximum', 'enum'} and type(field['required']) is bool, 'invalid_catalog')
+        kind = field['type']; values = field.get('enum', [])
+        if kind == 'string':
+            limit = field.get('max_length')
+            _check(type(limit) is int and 1 <= limit <= 16000 and 'minimum' not in field and 'maximum' not in field and type(values) is list and len(values) <= 64 and all(type(v) is str and len(v) <= limit for v in values) and len(set(values)) == len(values), 'invalid_catalog')
+        elif kind in ('number', 'integer'):
+            bounds = [field[key] for key in ('minimum', 'maximum') if key in field]
+            _check(not field.get('max_length') and not values and all(type(n) in (int, float) and abs(n) < math.inf and (kind != 'integer' or int(n) == n and abs(n) <= 9007199254740991) for n in bounds) and field.get('minimum', -math.inf) <= field.get('maximum', math.inf), 'invalid_catalog')
+        else:
+            _check(kind == 'boolean' and not field.get('max_length') and not values and 'minimum' not in field and 'maximum' not in field, 'invalid_catalog')
+
+def validate_action_catalog(version: str, actions: list) -> None:
+    _check(isinstance(version, str) and len(version) <= 32 and bool(re.fullmatch(r'(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)', version)) and type(actions) is list and 1 <= len(actions) <= 32, 'invalid_catalog')
+    names = set()
+    for action in actions:
+        _check(type(action) is dict and all(key in action for key in ('name', 'version', 'identity_required', 'risk', 'idempotency_supported', 'safe_retry', 'timeout_seconds', 'endpoint', 'input', 'output')), 'invalid_catalog')
+        name = action['name']
+        _check(type(name) is str and bool(re.fullmatch(r'[a-z][a-z0-9_.]{0,79}', name)) and name not in names and action['version'] == version and action['identity_required'] is True and action['risk'] in ('read', 'bounded_write', 'customer_change', 'financial', 'security') and type(action['idempotency_supported']) is bool and type(action['safe_retry']) is bool and type(action['timeout_seconds']) is int and 1 <= action['timeout_seconds'] <= 30 and _endpoint(action['endpoint']), 'invalid_catalog')
+        _check((action['risk'] == 'read' or action['idempotency_supported'] and _endpoint(action.get('reconciliation_endpoint')) and action.get('verification_operation')) and (not action['safe_retry'] or action['idempotency_supported']) and (not action.get('reconciliation_endpoint') or _endpoint(action['reconciliation_endpoint'])), 'invalid_catalog')
+        _fields(action['input'], True); _fields(action['output'], False); names.add(name)
+    for action in actions:
+        _check(not action.get('verification_operation') or any(a['name'] == action['verification_operation'] and a['risk'] == 'read' for a in actions), 'invalid_catalog')

stackshift-1.3.0/stackshift/support_action_receiver.py

@@ -0,0 +1,58 @@
+"""Durable claims are required; no in-memory fallback or automatic lease takeover."""
+import hashlib
+import time
+from dataclasses import dataclass
+from typing import Callable, Optional, Protocol
+from .support_actions import (ActionProtocolError, REQUEST_CONTEXT, RECEIPT_CONTEXT, encode_receipt,
+                              sign_action, validate_fields, verify_action)
+
+@dataclass(frozen=True)
+class ActionClaim:
+    state: str  # acquired, completed, running, unknown, conflict
+    fence: str = ""
+    response: Optional[bytes] = None
+
+class ActionDurableStore(Protocol):
+    def claim(self, namespace: str, key: str, digest: str) -> ActionClaim: ...
+    def complete(self, namespace: str, key: str, fence: str, response: bytes, unknown: bool = False) -> None: ...
+
+@dataclass(frozen=True)
+class SignedActionResponse:
+    body: bytes
+    headers: dict
+
+def receive_action(raw: bytes, headers: dict, *, store: ActionDurableStore, execute: Callable,
+                   reconcile: Callable, verification: dict) -> SignedActionResponse:
+    options = dict(verification)
+    now = options.setdefault("now", int(time.time()))
+    request = verify_action(raw, headers, **options)
+    normalized = {name.lower(): value for name, value in headers.items()}
+    delivery = normalized["x-stackshift-delivery-id"]
+    digest = hashlib.sha256(raw).hexdigest()
+    delivery_key = request["installation_id"] + ":" + delivery
+    delivery_claim = store.claim("delivery", delivery_key, digest)
+    if delivery_claim.state != "acquired":
+        raise ActionProtocolError("delivery_replay")
+    key = ":".join((request["installation_id"], request["action"]["name"], request["action"]["version"], request["request_id"], request["mode"]))
+    claim = store.claim("execution", key, digest)
+    if claim.state == "conflict":
+        raise ActionProtocolError("idempotency_conflict")
+    if claim.state in ("completed", "unknown") and claim.response is not None:
+        response = claim.response
+    elif claim.state in ("running", "unknown"):
+        response = encode_receipt(request["request_id"], "unknown" if claim.state == "unknown" else "accepted", {}, "execution_unknown" if claim.state == "unknown" else "execution_in_progress")
+    elif claim.state == "acquired":
+        try:
+            handler = reconcile if request["mode"] == "reconcile" else execute
+            state, result, code = handler(request)
+            action = next(a for a in options["actions"] if a["name"] == request["action"]["name"] and a["version"] == request["action"]["version"])
+            if state == "succeeded": validate_fields(result, action["output"])
+            response = encode_receipt(request["request_id"], state, result, code)
+        except Exception:
+            response = encode_receipt(request["request_id"], "unknown", {}, "handler_outcome_unknown")
+            state = "unknown"
+        store.complete("execution", key, claim.fence, response, state == "unknown")
+    else:
+        raise ActionProtocolError("invalid_store_claim")
+    store.complete("delivery", delivery_key, delivery_claim.fence, response)
+    return SignedActionResponse(response, sign_action(response, RECEIPT_CONTEXT, options["key_id"], options["secret"], now, delivery))

stackshift-1.3.0/stackshift/support_action_sqlite.py

@@ -0,0 +1,46 @@
+"""SQLite durable claims. Keep this database for the complete request/retry horizon."""
+import sqlite3
+import threading
+import uuid
+from .support_actions import ActionProtocolError
+from .support_action_receiver import ActionClaim
+
+class SQLiteActionStore:
+    def __init__(self, path: str):
+        if not path or path == ":memory:" or path.startswith("file:"):
+            raise ActionProtocolError("durable_database_required")
+        self._lock = threading.Lock()
+        self._db = sqlite3.connect(path, timeout=10, check_same_thread=False, isolation_level=None)
+        self._db.execute("PRAGMA journal_mode=WAL")
+        self._db.execute("PRAGMA synchronous=FULL")
+        self._db.execute("""CREATE TABLE IF NOT EXISTS support_action_claims (
+          namespace TEXT NOT NULL, claim_key TEXT NOT NULL, digest TEXT NOT NULL,
+          state TEXT NOT NULL, fence TEXT NOT NULL, response BLOB,
+          PRIMARY KEY(namespace,claim_key))""")
+
+    def claim(self, namespace: str, key: str, digest: str) -> ActionClaim:
+        with self._lock:
+            self._db.execute("BEGIN IMMEDIATE")
+            try:
+                fence = str(uuid.uuid4())
+                cursor = self._db.execute("INSERT OR IGNORE INTO support_action_claims VALUES(?,?,?,'running',?,NULL)", (namespace, key, digest, fence))
+                if cursor.rowcount == 1:
+                    result = ActionClaim("acquired", fence)
+                else:
+                    row = self._db.execute("SELECT digest,state,fence,response FROM support_action_claims WHERE namespace=? AND claim_key=?", (namespace, key)).fetchone()
+                    result = ActionClaim("conflict" if row[0] != digest else row[1], row[2], row[3])
+                self._db.execute("COMMIT")
+                return result
+            except BaseException:
+                self._db.execute("ROLLBACK")
+                raise
+
+    def complete(self, namespace: str, key: str, fence: str, response: bytes, unknown: bool = False) -> None:
+        with self._lock:
+            cursor = self._db.execute("UPDATE support_action_claims SET state=?,response=? WHERE namespace=? AND claim_key=? AND fence=? AND state='running'", ("unknown" if unknown else "completed", response, namespace, key, fence))
+            if cursor.rowcount != 1:
+                raise ActionProtocolError("fence_lost")
+
+    def close(self) -> None:
+        with self._lock:
+            self._db.close()