slidecold 0.1.0__py3-none-any.whl

slidecold/__init__.py

@@ -0,0 +1,32 @@
+"""Official Python SDK for the SlideCold API."""
+
+from ._client import AsyncSlideCold, SlideCold
+from ._config import DEFAULT_BASE_URL
+from ._exceptions import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    SlideColdError,
+)
+from ._operations import OPERATIONS
+from ._version import __version__
+from ._webhooks import verify_webhook_signature
+
+__all__ = [
+    "SlideCold",
+    "AsyncSlideCold",
+    "SlideColdError",
+    "APIError",
+    "APIConnectionError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "RateLimitError",
+    "verify_webhook_signature",
+    "OPERATIONS",
+    "DEFAULT_BASE_URL",
+    "__version__",
+]

slidecold/_client.py

@@ -0,0 +1,235 @@
+import asyncio
+import time
+from typing import Any, Dict, Optional
+from urllib.parse import quote
+
+import httpx
+
+from . import _config
+from ._exceptions import APIConnectionError, AuthenticationError, error_for_status
+from ._files import FileInput, to_upload
+from ._operations import OPERATIONS
+from ._resources import AsyncResources, SyncResources
+from ._version import __version__
+
+RETRY_STATUSES = {429, 500, 502, 503, 504}
+TERMINAL_JOB_STATES = {"completed", "failed", "unknown"}
+NO_KEY = "No SlideCold API key found. Pass api_key=..., set SLIDECOLD_API_KEY, or run `slidecold login`"
+
+
+class _BaseClient:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 30,
+        max_retries: int = 2,
+    ) -> None:
+        key, url = _config.resolve(api_key, base_url)
+        if not key:
+            raise AuthenticationError(None, NO_KEY)
+        self.api_key = key
+        self.base_url = url
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._headers = {
+            "Authorization": f"Bearer {key}",
+            "User-Agent": f"slidecold-python/{__version__}",
+            "Accept": "application/json",
+        }
+
+    def _build(
+        self,
+        operation_id: str,
+        path: Optional[Dict[str, Any]],
+        query: Optional[Dict[str, Any]],
+        body: Optional[Any],
+        file: Optional[FileInput],
+    ) -> Dict[str, Any]:
+        op = OPERATIONS[operation_id]
+        url = op.path
+        for p in op.path_params:
+            value = (path or {}).get(p.name)
+            if value is None or value == "":
+                raise ValueError(f"{operation_id}: missing path parameter {p.py_name!r}")
+            url = url.replace("{" + p.name + "}", quote(str(value), safe=""))
+        params = {}
+        for k, v in (query or {}).items():
+            if v is not None:
+                params[k] = ("true" if v else "false") if isinstance(v, bool) else v
+        request: Dict[str, Any] = {"method": op.method, "url": self.base_url + url, "params": params}
+        if file is not None:
+            if not op.file_field:
+                raise ValueError(f"{operation_id} does not accept a file")
+            request["files"] = {op.file_field: to_upload(file)}
+        elif op.body == "multipart":
+            raise ValueError(f"{operation_id} requires a file")
+        elif op.body:
+            if body is None and op.body_required:
+                body = {}
+            if body is not None:
+                request["json"] = body
+        return request
+
+    def _backoff(self, attempt: int, response: Optional[httpx.Response]) -> float:
+        retry_after = response.headers.get("retry-after") if response is not None else None
+        if retry_after and retry_after.replace(".", "", 1).isdigit():
+            return min(float(retry_after), 30.0)
+        return min(0.5 * 2.0**attempt, 8.0)
+
+    @staticmethod
+    def _parse(response: httpx.Response) -> Any:
+        ctype = response.headers.get("content-type", "")
+        if response.status_code >= 400:
+            body: Any = response.text
+            if "json" in ctype:
+                try:
+                    body = response.json()
+                except ValueError:
+                    pass
+            message = body.get("error") if isinstance(body, dict) else None
+            if not isinstance(message, str):
+                message = (
+                    (body if isinstance(body, str) and body else None) or response.reason_phrase or "Error"
+                )
+            raise error_for_status(response.status_code, message, body)
+        if not response.content:
+            return None
+        if "json" in ctype:
+            return response.json()
+        return response.text
+
+
+class SlideCold(_BaseClient, SyncResources):
+    """Synchronous SlideCold client.
+
+    >>> with SlideCold() as client:
+    ...     campaigns = client.campaigns.list()
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 30,
+        max_retries: int = 2,
+    ) -> None:
+        super().__init__(api_key, base_url, timeout, max_retries)
+        self._http = httpx.Client(headers=self._headers, timeout=timeout)
+        self._init_resources()
+
+    def request(
+        self,
+        operation_id: str,
+        *,
+        path: Optional[Dict[str, Any]] = None,
+        query: Optional[Dict[str, Any]] = None,
+        body: Optional[Any] = None,
+        file: Optional[FileInput] = None,
+    ) -> Any:
+        """Call any operation by its OpenAPI operationId. Only GETs are retried."""
+        req = self._build(operation_id, path, query, body, file)
+        retries = self.max_retries if req["method"] == "GET" else 0
+        attempt = 0
+        while True:
+            try:
+                response = self._http.request(**req)
+            except httpx.TransportError as e:
+                if attempt >= retries:
+                    raise APIConnectionError(None, f"Could not reach {self.base_url}: {e}") from e
+                time.sleep(self._backoff(attempt, None))
+            else:
+                if response.status_code not in RETRY_STATUSES or attempt >= retries:
+                    return self._parse(response)
+                time.sleep(self._backoff(attempt, response))
+            attempt += 1
+
+    def wait_for_login_job(self, job_id: str, interval: float = 2, timeout: float = 120) -> Dict[str, Any]:
+        """Poll `accounts.login_status` until the job is completed, failed or unknown; return the last status.
+
+        Raises TimeoutError if the job is still running after `timeout` seconds.
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            status: Dict[str, Any] = self.accounts.login_status(job_id)
+            if status.get("state") in TERMINAL_JOB_STATES:
+                return status
+            if time.monotonic() + interval > deadline:
+                raise TimeoutError(f"Login job {job_id} still {status.get('state')!r} after {timeout}s")
+            time.sleep(interval)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "SlideCold":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class AsyncSlideCold(_BaseClient, AsyncResources):
+    """Asynchronous SlideCold client (asyncio).
+
+    >>> async with AsyncSlideCold() as client:
+    ...     campaigns = await client.campaigns.list()
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 30,
+        max_retries: int = 2,
+    ) -> None:
+        super().__init__(api_key, base_url, timeout, max_retries)
+        self._http = httpx.AsyncClient(headers=self._headers, timeout=timeout)
+        self._init_resources()
+
+    async def request(
+        self,
+        operation_id: str,
+        *,
+        path: Optional[Dict[str, Any]] = None,
+        query: Optional[Dict[str, Any]] = None,
+        body: Optional[Any] = None,
+        file: Optional[FileInput] = None,
+    ) -> Any:
+        """Call any operation by its OpenAPI operationId. Only GETs are retried."""
+        req = self._build(operation_id, path, query, body, file)
+        retries = self.max_retries if req["method"] == "GET" else 0
+        attempt = 0
+        while True:
+            try:
+                response = await self._http.request(**req)
+            except httpx.TransportError as e:
+                if attempt >= retries:
+                    raise APIConnectionError(None, f"Could not reach {self.base_url}: {e}") from e
+                await asyncio.sleep(self._backoff(attempt, None))
+            else:
+                if response.status_code not in RETRY_STATUSES or attempt >= retries:
+                    return self._parse(response)
+                await asyncio.sleep(self._backoff(attempt, response))
+            attempt += 1
+
+    async def wait_for_login_job(
+        self, job_id: str, interval: float = 2, timeout: float = 120
+    ) -> Dict[str, Any]:
+        """Async version of `SlideCold.wait_for_login_job`."""
+        deadline = time.monotonic() + timeout
+        while True:
+            status: Dict[str, Any] = await self.accounts.login_status(job_id)
+            if status.get("state") in TERMINAL_JOB_STATES:
+                return status
+            if time.monotonic() + interval > deadline:
+                raise TimeoutError(f"Login job {job_id} still {status.get('state')!r} after {timeout}s")
+            await asyncio.sleep(interval)
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncSlideCold":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()

slidecold/_config.py

@@ -0,0 +1,44 @@
+"""API key and base URL resolution, shared with the Node and Go CLIs (`config.json`: {"apiKey", "baseUrl"})."""
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+
+DEFAULT_BASE_URL = "https://slidecold.com/api/v1"
+
+
+def config_path() -> Path:
+    if os.name == "nt":
+        base = os.environ.get("APPDATA") or str(Path.home() / "AppData" / "Roaming")
+    else:
+        base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "slidecold" / "config.json"
+
+
+def load_config() -> Dict[str, Any]:
+    try:
+        data = json.loads(config_path().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def save_config(data: Dict[str, Any]) -> Path:
+    """Write the config file readable only by the current user (0600)."""
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+    os.chmod(path, 0o600)  # the file may have existed with wider permissions
+    return path
+
+
+def resolve(api_key: Optional[str] = None, base_url: Optional[str] = None) -> Tuple[Optional[str], str]:
+    """Explicit argument, then SLIDECOLD_API_KEY / SLIDECOLD_BASE_URL, then the config file, then prod."""
+    config = load_config()
+    key = api_key or os.environ.get("SLIDECOLD_API_KEY") or config.get("apiKey") or None
+    url = base_url or os.environ.get("SLIDECOLD_BASE_URL") or config.get("baseUrl") or DEFAULT_BASE_URL
+    return key, str(url).rstrip("/")

slidecold/_exceptions.py

@@ -0,0 +1,48 @@
+from typing import Any, Optional
+
+KEYS_URL = "https://slidecold.com/settings"
+
+
+class SlideColdError(Exception):
+    """Base error. `status` is the HTTP status (None for connection errors), `body` the parsed response."""
+
+    def __init__(self, status: Optional[int], message: str, body: Any = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.message = message
+        self.body = body
+
+    def __str__(self) -> str:
+        return f"{self.message} (HTTP {self.status})" if self.status else self.message
+
+
+class APIConnectionError(SlideColdError):
+    """The request never got a response (DNS, refused connection, timeout)."""
+
+
+class APIError(SlideColdError):
+    """The API returned an error status. Specific statuses use the subclasses below."""
+
+
+class AuthenticationError(APIError):
+    """401: the API key is missing or invalid."""
+
+    def __init__(self, status: Optional[int], message: str, body: Any = None) -> None:
+        super().__init__(status, f"{message}. Create an API key at {KEYS_URL}", body)
+
+
+class PermissionDeniedError(APIError):
+    """403: the key is missing a scope (e.g. `campaigns:write`) or a plan limit was hit."""
+
+
+class NotFoundError(APIError):
+    """404."""
+
+
+class RateLimitError(APIError):
+    """429."""
+
+
+def error_for_status(status: int, message: str, body: Any) -> APIError:
+    cls = {401: AuthenticationError, 403: PermissionDeniedError, 404: NotFoundError, 429: RateLimitError}
+    return cls.get(status, APIError)(status, message, body)

slidecold/_files.py

@@ -0,0 +1,21 @@
+import mimetypes
+import os
+from pathlib import Path
+from typing import IO, Tuple, Union
+
+FileInput = Union[str, "os.PathLike[str]", bytes, IO[bytes], Tuple[str, bytes]]
+
+
+def to_upload(file: FileInput, default_name: str = "upload") -> Tuple[str, bytes, str]:
+    """Normalize a file argument into an httpx multipart tuple (filename, content, content_type)."""
+    # shortcut: reads the whole file into memory (fine for photos/CSVs); stream it if large uploads appear.
+    if isinstance(file, tuple):
+        name, content = file
+    elif isinstance(file, bytes):
+        name, content = default_name, file
+    elif isinstance(file, (str, os.PathLike)):
+        path = Path(file)
+        name, content = path.name, path.read_bytes()
+    else:
+        name, content = Path(getattr(file, "name", default_name)).name, file.read()
+    return name, content, mimetypes.guess_type(name)[0] or "application/octet-stream"

slidecold/_mcp.py

@@ -0,0 +1,121 @@
+"""MCP server exposing one tool per SlideCold API operation (requires the `mcp` extra)."""
+
+import json
+import os
+from typing import Any, Dict, List, Optional
+
+from mcp import types
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+
+from ._client import AsyncSlideCold
+from ._exceptions import SlideColdError
+from ._operations import OPERATIONS, Operation
+from ._version import __version__
+
+INSTRUCTIONS = (
+    "Tools for the SlideCold API (Instagram cold-DM outreach). Each tool needs the API key scope named in its "
+    "description; a 403 means the key lacks that scope or a plan limit was hit. Login jobs (create_account, "
+    "relogin_account, check_account_session) return a jobId to poll with get_login_status."
+)
+
+
+def tool_schema(op: Operation) -> Dict[str, Any]:
+    props: Dict[str, Any] = {}
+    required: List[str] = []
+    for p in (*op.path_params, *op.query_params):
+        props[p.name] = {**p.schema, **({"description": p.description} if p.description else {})}
+        if p.required:
+            required.append(p.name)
+    if op.body_schema is not None:
+        if op.body_flat:
+            props.update(op.body_schema.get("properties", {}))
+            if op.body_required:
+                required += op.body_schema.get("required", [])
+        else:
+            props["body"] = op.body_schema
+            if op.body_required and not op.file_field:
+                required.append("body")
+    if op.file_field:
+        props["file_path"] = {
+            "type": "string",
+            "description": f"Path to a local file to upload as `{op.file_field}`.",
+        }
+        if op.body == "multipart":
+            required.append("file_path")
+    schema: Dict[str, Any] = {"type": "object", "properties": props}
+    if required:
+        schema["required"] = required
+    return schema
+
+
+def make_tool(op: Operation) -> types.Tool:
+    description = op.summary + "."
+    if op.description:
+        description += "\n\n" + op.description
+    description += f"\n\nRequired API key scope: {op.scope}"
+    read_only = op.method == "GET"
+    return types.Tool(
+        name=op.tool,
+        description=description,
+        input_schema=tool_schema(op),
+        annotations=types.ToolAnnotations(
+            title=op.summary,
+            read_only_hint=read_only,
+            destructive_hint=None if read_only else op.destructive,
+        ),
+    )
+
+
+TOOLS = {op.tool: (op, make_tool(op)) for op in OPERATIONS.values()}
+
+
+def _text(text: str, error: bool = False) -> types.CallToolResult:
+    return types.CallToolResult(content=[types.TextContent(type="text", text=text)], is_error=error)
+
+
+def build_server(client: Optional[AsyncSlideCold] = None) -> Server:
+    """Build the server. Without `client`, one is created on the first tool call from env/config."""
+    state: Dict[str, AsyncSlideCold] = {"client": client} if client else {}
+
+    async def list_tools(ctx: Any, params: Any) -> types.ListToolsResult:
+        return types.ListToolsResult(tools=[tool for _, tool in TOOLS.values()])
+
+    async def call_tool(ctx: Any, params: types.CallToolRequestParams) -> types.CallToolResult:
+        if params.name not in TOOLS:
+            return _text(f"Unknown tool: {params.name}", error=True)
+        op = TOOLS[params.name][0]
+        args = dict(params.arguments or {})
+        try:
+            if "client" not in state:
+                state["client"] = AsyncSlideCold()
+            file_path = args.pop("file_path", None)
+            path = {p.name: args.pop(p.name, None) for p in op.path_params}
+            query = {q.name: args.pop(q.name, None) for q in op.query_params}
+            body = (args or None) if op.body_flat else args.pop("body", None)
+            result = await state["client"].request(
+                op.id,
+                path=path,
+                query=query,
+                body=body,
+                file=os.path.expanduser(file_path) if file_path else None,
+            )
+        except (SlideColdError, ValueError, OSError) as e:
+            return _text(str(e), error=True)
+        if result is None:
+            return _text("OK")
+        return _text(result if isinstance(result, str) else json.dumps(result, indent=2, ensure_ascii=False))
+
+    return Server(
+        "slidecold",
+        version=__version__,
+        instructions=INSTRUCTIONS,
+        on_list_tools=list_tools,
+        on_call_tool=call_tool,
+    )
+
+
+async def serve_stdio() -> None:
+    server = build_server()
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())