stackshift 1.2.1__tar.gz → 1.3.1__tar.gz

{stackshift-1.2.1 → stackshift-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackshift
-Version: 1.2.1
+Version: 1.3.1
 Summary: Official Python SDK for StackShift.
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -16,6 +16,25 @@ Official Python SDK for StackShift.
 pip install stackshift
 ```
 
+## Partner platforms
+
+Staff-enabled partner accounts buy domains for merchants from their StackShift wallet. Use an API token with the `partner:manage` scope (and `mail:manage` to run campaigns) on your server:
+
+```python
+domain = stackshift.partner.purchase_domain(
+    domain="merchantshop.com",
+    years=1,
+    merchant_ref="m_123",
+    registrant={"first_name": "Ada", "last_name": "Obi", "email": "ada@merchantshop.com", "phone": "+2348012345678", "address": "1 Marina", "city": "Lagos", "state": "Lagos", "postal_code": "101001", "country": "NG"},
+    brand={"name": "Merchant Shop", "postalAddress": "1 Marina, Lagos, Nigeria"},
+    replies={"mode": "forward", "forwardTo": "ada@gmail.com"},
+    idempotency_key="order-m_123-1",
+)
+status = stackshift.partner.get_domain(domain["id"])
+```
+
+`partner` also exposes `overview`, `update_settings`, `list_domains` (with `q` and `attention` to find the merchants that need you), `retry_domain`, `get_diagnosis`, `restore_dns`, `transfer_out`, `resume_brand`, `get_complaints`, `list_complaint_sources`, `suppress_never_opened`, `undo_suppression`, `usage`, `list_requests` and `create_request`. `transfer_out` needs the `partner:transfer` scope (or `*`); `partner:manage` alone is refused. Purchases are capped at 30 per minute and, per partner, at 25 domains in a rolling 24 hours (429 `daily_purchase_limit`; staff can raise it). Validation errors are 400, state conflicts are 409. The `brand` and `replies` dictionaries use API camelCase keys.
+
 ## AI credits
 
 AI credits are account-scoped. Use the shared client to inspect usage, start a top-up, or select managed billing versus your own provider key:
@@ -101,6 +120,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 +330,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.1 → stackshift-1.3.1}/README.md

@@ -8,6 +8,25 @@ Official Python SDK for StackShift.
 pip install stackshift
 ```
 
+## Partner platforms
+
+Staff-enabled partner accounts buy domains for merchants from their StackShift wallet. Use an API token with the `partner:manage` scope (and `mail:manage` to run campaigns) on your server:
+
+```python
+domain = stackshift.partner.purchase_domain(
+    domain="merchantshop.com",
+    years=1,
+    merchant_ref="m_123",
+    registrant={"first_name": "Ada", "last_name": "Obi", "email": "ada@merchantshop.com", "phone": "+2348012345678", "address": "1 Marina", "city": "Lagos", "state": "Lagos", "postal_code": "101001", "country": "NG"},
+    brand={"name": "Merchant Shop", "postalAddress": "1 Marina, Lagos, Nigeria"},
+    replies={"mode": "forward", "forwardTo": "ada@gmail.com"},
+    idempotency_key="order-m_123-1",
+)
+status = stackshift.partner.get_domain(domain["id"])
+```
+
+`partner` also exposes `overview`, `update_settings`, `list_domains` (with `q` and `attention` to find the merchants that need you), `retry_domain`, `get_diagnosis`, `restore_dns`, `transfer_out`, `resume_brand`, `get_complaints`, `list_complaint_sources`, `suppress_never_opened`, `undo_suppression`, `usage`, `list_requests` and `create_request`. `transfer_out` needs the `partner:transfer` scope (or `*`); `partner:manage` alone is refused. Purchases are capped at 30 per minute and, per partner, at 25 domains in a rolling 24 hours (429 `daily_purchase_limit`; staff can raise it). Validation errors are 400, state conflicts are 409. The `brand` and `replies` dictionaries use API camelCase keys.
+
 ## AI credits
 
 AI credits are account-scoped. Use the shared client to inspect usage, start a top-up, or select managed billing versus your own provider key:
@@ -93,6 +112,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 +322,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.1 → stackshift-1.3.1}/pyproject.toml

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

{stackshift-1.2.1 → stackshift-1.3.1}/stackshift/__init__.py

@@ -13,6 +13,15 @@ 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 .partner import PartnerClient
 from .projects import ProjectsClient
 from .workload_security import WorkloadSecurityClient
 
@@ -35,6 +44,13 @@ __all__ = [
     "MailAudiencesClient",
     "MailCampaignsClient",
     "MailExportsClient",
+    "MailboxAliasesClient",
+    "MailboxDomainsClient",
+    "MailboxGroupsClient",
+    "MailboxImportsClient",
+    "MailboxesClient",
+    "MailboxRoutesClient",
+    "PartnerClient",
     "ProjectsClient",
     "WorkloadSecurityClient",
     "asset_transform_options",
@@ -42,3 +58,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.1 → stackshift-1.3.1}/stackshift/assets.py

@@ -230,6 +230,23 @@ class AssetsClient(AssetWorkflowsMixin):
         headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
         return self._client.request("POST", path, headers=headers)
 
+    def usage(self, asset_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/assets/{quote(asset_id, safe='')}/usage")
+
+    def hold(self, asset_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/assets/{quote(asset_id, safe='')}/hold")
+
+    def create_reupload_request(
+        self, asset_id: str, *, email: str | None = None, message: str | None = None
+    ) -> dict[str, Any]:
+        payload = {key: value for key, value in {"email": email, "message": message}.items() if value}
+        return self._client.request(
+            "POST", f"/assets/{quote(asset_id, safe='')}/reupload-requests", json=payload
+        )
+
+    def reupload_requests(self, asset_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/assets/{quote(asset_id, safe='')}/reupload-requests")
+
     def versions(self, asset_id: str) -> dict[str, Any]:
         return self._client.request("GET", f"/assets/{asset_id}/versions")
 

{stackshift-1.2.1 → stackshift-1.3.1}/stackshift/assets_workflows.py

@@ -17,6 +17,14 @@ class AssetWorkflowsMixin:
             json={"name": name, "definition": definition, "eager": eager},
         )
 
+    def estimate_transform(
+        self, asset_id: str, version_id: str, definition: dict[str, Any]
+    ) -> dict[str, Any]:
+        return self._client.request(
+            "POST", f"/assets/{quote(asset_id, safe='')}/transforms/estimate",
+            json={"version_id": version_id, "definition": definition},
+        )
+
     def materialize_transform(
         self,
         asset_id: str,

{stackshift-1.2.1 → stackshift-1.3.1}/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:
@@ -29,6 +29,7 @@ class StackShift:
         from .ai_credits import AICreditsClient
         from .assets import AssetsClient
         from .mail import MailClient
+        from .partner import PartnerClient
         from .projects import ProjectsClient
         from .workload_security import WorkloadSecurityClient
 
@@ -36,6 +37,7 @@ class StackShift:
         self.projects = ProjectsClient(self)
         self.assets = AssetsClient(self)
         self.mail = MailClient(self)
+        self.partner = PartnerClient(self)
         self.workload_security = WorkloadSecurityClient(self)
 
     def request(self, method: str, path: str, **kwargs: Any) -> Any:

{stackshift-1.2.1 → stackshift-1.3.1}/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)
@@ -297,12 +311,14 @@ class MailSuppressionsClient:
         *,
         email: str | None = None,
         reason: str | None = None,
+        brand_id: str | None = None,
         limit: int | None = None,
         cursor: str | None = None,
     ) -> dict[str, Any]:
         params = {
             "email": email,
             "reason": reason,
+            "brandId": brand_id,
             "limit": limit,
             "cursor": cursor,
         }

{stackshift-1.2.1 → stackshift-1.3.1}/stackshift/mail_billing.py

@@ -7,3 +7,6 @@ class MailBillingClient:
 
     def summary(self) -> dict[str, Any]:
         return self._client.mail_request("GET", "/mail/billing")
+
+    def period_usage(self, period: str) -> dict[str, Any]:
+        return self._client.mail_request("GET", "/mail/billing", params={"period": period})

{stackshift-1.2.1 → stackshift-1.3.1}/stackshift/mail_brands.py

@@ -28,7 +28,7 @@ class MailBrandsClient:
 
 
 def _brand_fields(fields: dict[str, Any]) -> dict[str, Any]:
-    names = {"logo_url": "logoUrl", "sending_domain_id": "sendingDomainId", "default_from": "defaultFrom", "reply_to": "replyTo", "postal_address": "postalAddress", "website": "website", "support_email": "supportEmail", "editable_fields": "editableFields"}
+    names = {"logo_url": "logoUrl", "sending_domain_id": "sendingDomainId", "default_from": "defaultFrom", "reply_to": "replyTo", "postal_address": "postalAddress", "website": "website", "support_email": "supportEmail", "editable_fields": "editableFields", "merchant_ref": "merchantRef"}
     unknown = fields.keys() - names.keys() - set(names.values())
     if unknown:
         raise ValueError("Unknown brand fields: " + ", ".join(sorted(unknown)))

{stackshift-1.2.1 → stackshift-1.3.1}/stackshift/mail_campaigns.py

@@ -12,8 +12,9 @@ class MailAudiencesClient:
         payload = {"brandId": brand_id, "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 list(self, *, brand_id: str | None = None) -> dict[str, Any]:
+        params = {"brandId": brand_id} if brand_id else None
+        return self._client.mail_request("GET", "/mail/audiences", params=params)
 
     def get(self, audience_id: str) -> dict[str, Any]:
         return self._client.mail_request("GET", f"/mail/audiences/{quote(audience_id, safe='')}")
@@ -58,8 +59,8 @@ class MailCampaignsClient:
     def create(
         self,
         *,
-        name: str,
         audience_id: str,
+        name: str | None = None,
         template: str = "",
         from_: str = "",
         version_id: str | None = None,
@@ -83,8 +84,9 @@ class MailCampaignsClient:
         }
         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 list(self, *, brand_id: str | None = None) -> dict[str, Any]:
+        params = {"brandId": brand_id} if brand_id else None
+        return self._client.mail_request("GET", "/mail/campaigns", params=params)
 
     def get(self, campaign_id: str) -> dict[str, Any]:
         return self._client.mail_request("GET", f"/mail/campaigns/{quote(campaign_id)}")

{stackshift-1.2.1 → stackshift-1.3.1}/stackshift/mail_events_webhooks.py

@@ -79,6 +79,15 @@ class MailWebhooksClient:
     def rotate_secret(self, webhook_id: str) -> dict[str, Any]:
         return self._client.mail_request("POST", f"/mail/webhooks/{quote(webhook_id)}/rotate-secret")
 
+    def reveal_secret(self, webhook_id: str) -> dict[str, Any]:
+        return self._client.mail_request("POST", f"/mail/webhooks/{quote(webhook_id)}/reveal-secret")
+
+    def diagnosis(self, webhook_id: str) -> dict[str, Any]:
+        return self._client.mail_request("GET", f"/mail/webhooks/{quote(webhook_id)}/diagnosis")
+
+    def diagnose(self, webhook_id: str) -> dict[str, Any]:
+        return self._client.mail_request("POST", f"/mail/webhooks/{quote(webhook_id)}/diagnosis")
+
     def delete(self, webhook_id: str) -> None:
         self._client.mail_request("DELETE", f"/mail/webhooks/{quote(webhook_id)}")