gork-sdk 1.0.0__tar.gz

gork_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: gork-sdk
+Version: 1.0.0
+Summary: Official Python SDK for gork.email programmable email infrastructure for AI agents
+Author: gork.email
+License: MIT
+Project-URL: Homepage, https://gork.email
+Project-URL: Documentation, https://gork.email/docs
+Project-URL: Repository, https://github.com/shyamcxy/gork-sdk
+Keywords: email,agent,ai,mcp,inbox,mail
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# gork-sdk — Python SDK for gork.email
+
+Programmable email infrastructure for AI agents. Provision inboxes, send and receive mail, manage threads, webhooks, domains, keys, and suppressions.
+
+## Install
+
+```bash
+pip install gork-sdk
+```
+
+## Quickstart
+
+```python
+from gork import GorkClient
+
+gork = GorkClient()  # reads GORK_KEY / GORK_API_KEY
+
+inbox = gork.create_inbox(username="sdr-alex", name="SDR Alex")
+print(inbox["address"])  # sdr-alex@gork.email
+
+gork.send_message(
+    inbox_id=inbox["id"],
+    to=["prospect@acme.com"],
+    subject="Quick intro",
+    text="Hi — wanted to share what we're building.",
+    idempotency_key="outreach-001",  # safe retries
+)
+```
+
+## Webhook verification
+
+```python
+from gork import verify_signature
+
+ok = verify_signature(raw_body, request.headers["X-Gork-Signature"], webhook_secret)
+```
+
+## Links
+
+- Docs: https://gork.email/docs
+- API reference: https://api.gork.email/openapi.json
+- Changelog: https://gork.email/changelog

gork_sdk-1.0.0/README.md

@@ -0,0 +1,42 @@
+# gork-sdk — Python SDK for gork.email
+
+Programmable email infrastructure for AI agents. Provision inboxes, send and receive mail, manage threads, webhooks, domains, keys, and suppressions.
+
+## Install
+
+```bash
+pip install gork-sdk
+```
+
+## Quickstart
+
+```python
+from gork import GorkClient
+
+gork = GorkClient()  # reads GORK_KEY / GORK_API_KEY
+
+inbox = gork.create_inbox(username="sdr-alex", name="SDR Alex")
+print(inbox["address"])  # sdr-alex@gork.email
+
+gork.send_message(
+    inbox_id=inbox["id"],
+    to=["prospect@acme.com"],
+    subject="Quick intro",
+    text="Hi — wanted to share what we're building.",
+    idempotency_key="outreach-001",  # safe retries
+)
+```
+
+## Webhook verification
+
+```python
+from gork import verify_signature
+
+ok = verify_signature(raw_body, request.headers["X-Gork-Signature"], webhook_secret)
+```
+
+## Links
+
+- Docs: https://gork.email/docs
+- API reference: https://api.gork.email/openapi.json
+- Changelog: https://gork.email/changelog

gork_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gork-sdk"
+version = "1.0.0"
+description = "Official Python SDK for gork.email programmable email infrastructure for AI agents"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "gork.email" }]
+keywords = ["email", "agent", "ai", "mcp", "inbox", "mail"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Communications :: Email",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://gork.email"
+Documentation = "https://gork.email/docs"
+Repository = "https://github.com/shyamcxy/gork-sdk"
+
+[tool.setuptools.packages.find]
+where = ["src"]

gork_sdk-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gork_sdk-1.0.0/src/gork/__init__.py

@@ -0,0 +1,19 @@
+"""gork.email Python SDK — programmable email infrastructure for AI agents."""
+
+from .client import GorkClient
+from .errors import GorkError
+from .types import Inbox, Message, Thread, Webhook, ApiKey, Domain, Suppression
+
+__all__ = [
+    "GorkClient",
+    "GorkError",
+    "Inbox",
+    "Message",
+    "Thread",
+    "Webhook",
+    "ApiKey",
+    "Domain",
+    "Suppression",
+]
+
+__version__ = "1.0.0"

gork_sdk-1.0.0/src/gork/client.py

@@ -0,0 +1,180 @@
+"""GorkClient — zero-dependency (stdlib only) REST client for api.gork.email."""
+
+import hashlib
+import hmac
+import json
+import os
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+from .errors import GorkError
+
+DEFAULT_BASE_URL = "https://api.gork.email"
+
+
+def verify_signature(payload: str, signature_header: str, secret: str) -> bool:
+    """Verify an X-Gork-Signature webhook header (HMAC-SHA256, timestamp-tolerated)."""
+    try:
+        parts = dict(p.split("=", 1) for p in signature_header.split(",") if "=" in p)
+        timestamp, signature = parts.get("t", ""), parts.get("v1", "")
+        if not timestamp or not signature:
+            return False
+        expected = hmac.new(
+            secret.encode(), f"{timestamp}.{payload}".encode(), hashlib.sha256
+        ).hexdigest()
+        return hmac.compare_digest(signature, expected)
+    except Exception:
+        return False
+
+
+class GorkClient:
+    def __init__(self, api_key: str = "", base_url: str = DEFAULT_BASE_URL):
+        self.api_key = api_key or os.environ.get("GORK_KEY") or os.environ.get("GORK_API_KEY") or ""
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        if not self.api_key:
+            import warnings
+
+            warnings.warn(
+                "[gork] initialized without an api_key. Set GORK_KEY or pass api_key explicitly."
+            )
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+        query: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        url = self.base_url + path
+        if query:
+            url += "?" + urllib.parse.urlencode({k: v for k, v in query.items() if v is not None})
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(url, data=data, method=method)
+        req.add_header("Authorization", f"Bearer {self.api_key}")
+        req.add_header("Content-Type", "application/json")
+        req.add_header("User-Agent", "gork-sdk-python/1.0.0")
+        for k, v in (headers or {}).items():
+            req.add_header(k, v)
+        try:
+            with urllib.request.urlopen(req, timeout=30) as res:
+                payload = json.loads(res.read().decode() or "{}")
+        except urllib.error.HTTPError as e:
+            try:
+                payload = json.loads(e.read().decode() or "{}")
+            except Exception:
+                payload = {}
+            err = (payload.get("error") or {}) if isinstance(payload, dict) else {}
+            raise GorkError(
+                err.get("message") or f"API request failed with status {e.code}",
+                err.get("code") or "api_error",
+                e.code,
+                err.get("details"),
+            )
+        data_key = payload.get("data", payload) if isinstance(payload, dict) else payload
+        return data_key
+
+    # ---- Inboxes ----
+    def create_inbox(self, username: str = "", name: str = "") -> Dict[str, Any]:
+        return self._request("POST", "/v1/inboxes", {"username": username, "name": name})
+
+    def list_inboxes(self) -> List[Dict[str, Any]]:
+        return self._request("GET", "/v1/inboxes")
+
+    def get_inbox(self, inbox_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/v1/inboxes/{urllib.parse.quote(inbox_id)}")
+
+    def delete_inbox(self, inbox_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/v1/inboxes/{urllib.parse.quote(inbox_id)}")
+
+    # ---- Messages ----
+    def send_message(
+        self,
+        inbox_id: str,
+        to: List[str],
+        subject: str = "(no subject)",
+        text: str = "",
+        html: str = "",
+        in_reply_to: str = "",
+        idempotency_key: str = "",
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"inboxId": inbox_id, "to": to, "subject": subject}
+        if text:
+            body["text"] = text
+        if html:
+            body["html"] = html
+        if in_reply_to:
+            body["inReplyTo"] = in_reply_to
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self._request("POST", "/v1/messages/send", body, headers=headers)
+
+    def list_messages(
+        self, inbox_id: str = "", thread_id: str = "", limit: int = 50
+    ) -> List[Dict[str, Any]]:
+        return self._request(
+            "GET", "/v1/messages",
+            query={"inboxId": inbox_id or None, "threadId": thread_id or None, "limit": limit},
+        )
+
+    def get_message(self, message_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/v1/messages/{urllib.parse.quote(message_id)}")
+
+    # ---- Threads ----
+    def list_threads(self) -> List[Dict[str, Any]]:
+        return self._request("GET", "/v1/threads")
+
+    def get_thread(self, thread_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/v1/threads/{urllib.parse.quote(thread_id)}")
+
+    # ---- Webhooks ----
+    def create_webhook(self, url: str, events: Optional[List[str]] = None) -> Dict[str, Any]:
+        return self._request(
+            "POST", "/v1/webhooks",
+            {"url": url, "subscribedEvents": events or ["email.received", "email.sent", "email.bounced"]},
+        )
+
+    def list_webhooks(self) -> List[Dict[str, Any]]:
+        return self._request("GET", "/v1/webhooks")
+
+    def rotate_webhook_secret(self, webhook_id: str) -> Dict[str, Any]:
+        return self._request("POST", f"/v1/webhooks/{urllib.parse.quote(webhook_id)}/rotate-secret")
+
+    def delete_webhook(self, webhook_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/v1/webhooks/{urllib.parse.quote(webhook_id)}")
+
+    def list_deliveries(self, limit: int = 50) -> List[Dict[str, Any]]:
+        return self._request("GET", "/v1/webhooks/deliveries", query={"limit": limit})
+
+    # ---- API keys ----
+    def create_api_key(self, name: str, scopes: Optional[List[str]] = None) -> Dict[str, Any]:
+        return self._request("POST", "/v1/keys", {"name": name, "scopes": scopes or ["*"]})
+
+    def list_api_keys(self) -> List[Dict[str, Any]]:
+        return self._request("GET", "/v1/keys")
+
+    def revoke_api_key(self, key_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/v1/keys/{urllib.parse.quote(key_id)}")
+
+    # ---- Domains ----
+    def create_domain(self, domain: str) -> Dict[str, Any]:
+        return self._request("POST", "/v1/domains", {"domain": domain})
+
+    def list_domains(self) -> List[Dict[str, Any]]:
+        return self._request("GET", "/v1/domains")
+
+    def verify_domain(self, domain_id: str) -> Dict[str, Any]:
+        return self._request("POST", f"/v1/domains/{urllib.parse.quote(domain_id)}/verify")
+
+    def delete_domain(self, domain_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/v1/domains/{urllib.parse.quote(domain_id)}")
+
+    # ---- Suppressions ----
+    def list_suppressions(self) -> List[Dict[str, Any]]:
+        return self._request("GET", "/v1/suppressions")
+
+    def suppress(self, email: str, reason: str = "manual") -> Dict[str, Any]:
+        return self._request("POST", "/v1/suppressions", {"email": email, "reason": reason})
+
+    def unsuppress(self, suppression_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/v1/suppressions/{urllib.parse.quote(suppression_id)}")

gork_sdk-1.0.0/src/gork/errors.py

@@ -0,0 +1,9 @@
+"""Error type carrying the API's stable error code."""
+
+
+class GorkError(Exception):
+    def __init__(self, message: str, code: str = "api_error", status: int = 0, details=None):
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.details = details

gork_sdk-1.0.0/src/gork/types.py

@@ -0,0 +1,59 @@
+"""TypedDict shapes mirroring the gork.email API envelopes."""
+
+from typing import List, Optional, TypedDict
+
+
+class Inbox(TypedDict, total=False):
+    id: str
+    address: str
+    name: Optional[str]
+    isActive: bool
+    createdAt: str
+
+
+class Message(TypedDict, total=False):
+    id: str
+    threadId: str
+    inboxId: str
+    direction: str
+    fromAddress: str
+    subject: str
+    textBody: Optional[str]
+    status: str
+    createdAt: str
+
+
+class Thread(TypedDict, total=False):
+    id: str
+    subject: str
+    messageCount: int
+    lastMessageAt: str
+
+
+class Webhook(TypedDict, total=False):
+    id: str
+    url: str
+    subscribedEvents: List[str]
+    isActive: bool
+    secret: Optional[str]
+
+
+class ApiKey(TypedDict, total=False):
+    id: str
+    name: str
+    keyPrefix: str
+    apiKey: Optional[str]
+    scopes: List[str]
+    createdAt: str
+
+
+class Domain(TypedDict, total=False):
+    id: str
+    domainName: str
+    status: str
+
+
+class Suppression(TypedDict, total=False):
+    id: str
+    email: str
+    reason: str

gork_sdk-1.0.0/src/gork_sdk.egg-info/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: gork-sdk
+Version: 1.0.0
+Summary: Official Python SDK for gork.email programmable email infrastructure for AI agents
+Author: gork.email
+License: MIT
+Project-URL: Homepage, https://gork.email
+Project-URL: Documentation, https://gork.email/docs
+Project-URL: Repository, https://github.com/shyamcxy/gork-sdk
+Keywords: email,agent,ai,mcp,inbox,mail
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# gork-sdk — Python SDK for gork.email
+
+Programmable email infrastructure for AI agents. Provision inboxes, send and receive mail, manage threads, webhooks, domains, keys, and suppressions.
+
+## Install
+
+```bash
+pip install gork-sdk
+```
+
+## Quickstart
+
+```python
+from gork import GorkClient
+
+gork = GorkClient()  # reads GORK_KEY / GORK_API_KEY
+
+inbox = gork.create_inbox(username="sdr-alex", name="SDR Alex")
+print(inbox["address"])  # sdr-alex@gork.email
+
+gork.send_message(
+    inbox_id=inbox["id"],
+    to=["prospect@acme.com"],
+    subject="Quick intro",
+    text="Hi — wanted to share what we're building.",
+    idempotency_key="outreach-001",  # safe retries
+)
+```
+
+## Webhook verification
+
+```python
+from gork import verify_signature
+
+ok = verify_signature(raw_body, request.headers["X-Gork-Signature"], webhook_secret)
+```
+
+## Links
+
+- Docs: https://gork.email/docs
+- API reference: https://api.gork.email/openapi.json
+- Changelog: https://gork.email/changelog

gork_sdk-1.0.0/src/gork_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+src/gork/__init__.py
+src/gork/client.py
+src/gork/errors.py
+src/gork/types.py
+src/gork_sdk.egg-info/PKG-INFO
+src/gork_sdk.egg-info/SOURCES.txt
+src/gork_sdk.egg-info/dependency_links.txt
+src/gork_sdk.egg-info/top_level.txt

gork_sdk-1.0.0/src/gork_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gork_sdk-1.0.0/src/gork_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+gork