smartlead-cli 0.1.0__tar.gz

smartlead_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 jzakirov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

smartlead_cli-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.3
+Name: smartlead-cli
+Version: 0.1.0
+Summary: Smartlead platform CLI
+Keywords: smartlead,cli,sales,outreach
+Author: OpenAI Codex
+License: MIT License
+         
+         Copyright (c) 2025 jzakirov
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Topic :: Utilities
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: tomlkit>=0.13.0
+Requires-Dist: typer>=0.12.0
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/jzakirov/smartlead-cli
+Project-URL: Source, https://github.com/jzakirov/smartlead-cli
+Project-URL: Issues, https://github.com/jzakirov/smartlead-cli/issues
+Description-Content-Type: text/markdown
+
+# smartlead-cli
+
+`smartlead-cli` provides a `smartlead` command for working with the Smartlead API from a terminal.
+
+It follows the same project structure as `plane-cli` and `wildberries-cli`: Typer commands, a shared config layer, JSON-first output, and a `raw` command for full API coverage.
+
+## Install
+
+```bash
+pip install smartlead-cli
+```
+
+## Authentication
+
+Smartlead uses an API key passed as `api_key` query parameter. Configure it once:
+
+```bash
+smartlead config init
+```
+
+You can also override at runtime:
+
+```bash
+SMARTLEAD_API_KEY=... smartlead campaigns list
+```
+
+## Config
+
+Config file path:
+
+- `~/.config/smartlead-cli/config.toml`
+
+Supported keys (examples):
+
+- `core.api_key`
+- `core.base_url`
+- `core.timeout_seconds`
+- `core.retries`
+- `defaults.limit`
+
+Examples:
+
+```bash
+smartlead config show
+smartlead config set core.timeout_seconds 30
+smartlead config set core.retries 3
+smartlead config set defaults.limit 100
+```
+
+## Commands (v1)
+
+- `config` - manage local config
+- `campaigns` - list/get/create/delete/update status + analytics/statistics + campaign leads
+- `leads` - a few global lead operations
+- `webhooks` - campaign webhook helpers
+- `raw` - direct API access for unsupported endpoints
+
+## Examples
+
+```bash
+smartlead campaigns list
+smartlead campaigns get 12345
+smartlead campaigns create --name "New Campaign"
+smartlead campaigns status 12345 --status PAUSED
+smartlead campaigns statistics 12345 --limit 50 --offset 0
+smartlead campaigns analytics top 12345
+smartlead campaigns analytics by-date 12345 --start-date 2025-01-01 --end-date 2025-01-31
+```
+
+Campaign leads:
+
+```bash
+smartlead campaigns leads list 12345
+smartlead campaigns leads add 12345 --body-file leads.json
+smartlead campaigns leads update 12345 67890 --body-file lead-update.json
+smartlead campaigns leads pause 12345 67890
+smartlead campaigns leads resume 12345 67890 --delay-days 2
+smartlead campaigns leads unsubscribe 12345 67890
+smartlead campaigns leads delete 12345 67890 --yes
+smartlead campaigns leads message-history 12345 67890
+```
+
+Global lead helpers:
+
+```bash
+smartlead leads get-by-email --email person@example.com
+smartlead leads unsubscribe-all 67890
+```
+
+Campaign webhooks:
+
+```bash
+smartlead webhooks list 12345
+smartlead webhooks upsert 12345 --body-file webhook.json
+smartlead webhooks delete 12345 --webhook-id 555 --yes
+```
+
+Raw endpoint access (fallback for full API surface):
+
+```bash
+smartlead raw request --method GET --path /campaigns
+smartlead raw request --method POST --path /campaigns/12345/status --query status=PAUSED
+smartlead raw request --method POST --path /campaigns/12345/leads --body-file leads.json
+```
+
+## Output
+
+- Default output is JSON on stdout
+- Errors are structured JSON on stderr
+- Use `--pretty` for Rich tables on selected list commands
+
+## Publishing to PyPI
+
+The repo includes a GitHub Actions workflow (`.github/workflows/publish.yml`) for trusted publishing on tags matching `v*`.
+
+## Notes
+
+- Smartlead API docs (official): https://helpcenter.smartlead.ai/en/articles/125-full-api-documentation
+- Smartlead API base URL defaulted in this CLI: `https://server.smartlead.ai/api/v1`
+- Rate limiting is handled with simple retries/backoff for `429` and `5xx`

smartlead_cli-0.1.0/README.md

@@ -0,0 +1,120 @@
+# smartlead-cli
+
+`smartlead-cli` provides a `smartlead` command for working with the Smartlead API from a terminal.
+
+It follows the same project structure as `plane-cli` and `wildberries-cli`: Typer commands, a shared config layer, JSON-first output, and a `raw` command for full API coverage.
+
+## Install
+
+```bash
+pip install smartlead-cli
+```
+
+## Authentication
+
+Smartlead uses an API key passed as `api_key` query parameter. Configure it once:
+
+```bash
+smartlead config init
+```
+
+You can also override at runtime:
+
+```bash
+SMARTLEAD_API_KEY=... smartlead campaigns list
+```
+
+## Config
+
+Config file path:
+
+- `~/.config/smartlead-cli/config.toml`
+
+Supported keys (examples):
+
+- `core.api_key`
+- `core.base_url`
+- `core.timeout_seconds`
+- `core.retries`
+- `defaults.limit`
+
+Examples:
+
+```bash
+smartlead config show
+smartlead config set core.timeout_seconds 30
+smartlead config set core.retries 3
+smartlead config set defaults.limit 100
+```
+
+## Commands (v1)
+
+- `config` - manage local config
+- `campaigns` - list/get/create/delete/update status + analytics/statistics + campaign leads
+- `leads` - a few global lead operations
+- `webhooks` - campaign webhook helpers
+- `raw` - direct API access for unsupported endpoints
+
+## Examples
+
+```bash
+smartlead campaigns list
+smartlead campaigns get 12345
+smartlead campaigns create --name "New Campaign"
+smartlead campaigns status 12345 --status PAUSED
+smartlead campaigns statistics 12345 --limit 50 --offset 0
+smartlead campaigns analytics top 12345
+smartlead campaigns analytics by-date 12345 --start-date 2025-01-01 --end-date 2025-01-31
+```
+
+Campaign leads:
+
+```bash
+smartlead campaigns leads list 12345
+smartlead campaigns leads add 12345 --body-file leads.json
+smartlead campaigns leads update 12345 67890 --body-file lead-update.json
+smartlead campaigns leads pause 12345 67890
+smartlead campaigns leads resume 12345 67890 --delay-days 2
+smartlead campaigns leads unsubscribe 12345 67890
+smartlead campaigns leads delete 12345 67890 --yes
+smartlead campaigns leads message-history 12345 67890
+```
+
+Global lead helpers:
+
+```bash
+smartlead leads get-by-email --email person@example.com
+smartlead leads unsubscribe-all 67890
+```
+
+Campaign webhooks:
+
+```bash
+smartlead webhooks list 12345
+smartlead webhooks upsert 12345 --body-file webhook.json
+smartlead webhooks delete 12345 --webhook-id 555 --yes
+```
+
+Raw endpoint access (fallback for full API surface):
+
+```bash
+smartlead raw request --method GET --path /campaigns
+smartlead raw request --method POST --path /campaigns/12345/status --query status=PAUSED
+smartlead raw request --method POST --path /campaigns/12345/leads --body-file leads.json
+```
+
+## Output
+
+- Default output is JSON on stdout
+- Errors are structured JSON on stderr
+- Use `--pretty` for Rich tables on selected list commands
+
+## Publishing to PyPI
+
+The repo includes a GitHub Actions workflow (`.github/workflows/publish.yml`) for trusted publishing on tags matching `v*`.
+
+## Notes
+
+- Smartlead API docs (official): https://helpcenter.smartlead.ai/en/articles/125-full-api-documentation
+- Smartlead API base URL defaulted in this CLI: `https://server.smartlead.ai/api/v1`
+- Rate limiting is handled with simple retries/backoff for `429` and `5xx`

smartlead_cli-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["uv_build>=0.10.4,<0.11.0"]
+build-backend = "uv_build"
+
+[project]
+name = "smartlead-cli"
+version = "0.1.0"
+description = "Smartlead platform CLI"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [{ name = "OpenAI Codex" }]
+dependencies = [
+    "httpx>=0.27.0",
+    "rich>=13.7.0",
+    "tomlkit>=0.13.0",
+    "typer>=0.12.0",
+]
+keywords = ["smartlead", "cli", "sales", "outreach"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Environment :: Console",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/jzakirov/smartlead-cli"
+Source = "https://github.com/jzakirov/smartlead-cli"
+Issues = "https://github.com/jzakirov/smartlead-cli/issues"
+
+[project.scripts]
+smartlead = "smartlead_cli.main:app"
+
+[tool.uv.build-backend]
+module-name = "smartlead_cli"
+module-root = ""
+
+[dependency-groups]
+dev = ["ruff>=0.9.0"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"

smartlead_cli-0.1.0/smartlead_cli/__init__.py

@@ -0,0 +1,5 @@
+"""smartlead-cli package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

smartlead_cli-0.1.0/smartlead_cli/args.py

@@ -0,0 +1,57 @@
+"""CLI argument parsing helpers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Iterable
+
+from smartlead_cli.output import read_text_arg
+
+
+def load_json_input(body_json: str | None = None, body_file: str | None = None) -> Any:
+    if body_json and body_file:
+        raise ValueError("Use only one of --body-json or --body-file")
+    if body_json is None and body_file is None:
+        raise ValueError("Body JSON is required")
+
+    if body_json is not None:
+        text = read_text_arg(body_json)
+    elif body_file == "-":
+        text = read_text_arg("-")
+    else:
+        text = Path(str(body_file)).read_text()
+
+    return json.loads(text)
+
+
+def maybe_load_json_input(body_json: str | None = None, body_file: str | None = None) -> Any | None:
+    if body_json is None and body_file is None:
+        return None
+    return load_json_input(body_json=body_json, body_file=body_file)
+
+
+def parse_kv_pairs(items: Iterable[str]) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for item in items:
+        key, value = _split_kv(item)
+        out[key] = value
+    return out
+
+
+def parse_json_kv_pairs(items: Iterable[str]) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    for item in items:
+        key, value = _split_kv(item)
+        out[key] = json.loads(value)
+    return out
+
+
+def _split_kv(item: str) -> tuple[str, str]:
+    if "=" not in item:
+        raise ValueError(f"Expected KEY=VALUE, got '{item}'")
+    key, value = item.split("=", 1)
+    key = key.strip()
+    if not key:
+        raise ValueError(f"Expected KEY=VALUE, got '{item}'")
+    return key, value

smartlead_cli-0.1.0/smartlead_cli/client.py

@@ -0,0 +1,179 @@
+"""HTTP client wrapper for Smartlead API."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urljoin
+
+import httpx
+import typer
+
+from smartlead_cli.output import print_error
+from smartlead_cli.serialize import to_data
+
+if TYPE_CHECKING:
+    from smartlead_cli.config import Config
+
+
+RETRYABLE_STATUS_CODES = {429, 500, 502, 503, 504}
+
+
+@dataclass
+class ResponseEnvelope:
+    status_code: int
+    headers: dict[str, str]
+    data: Any
+
+
+@dataclass
+class SmartleadClient:
+    cfg: "Config"
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: Any | None = None,
+        headers: dict[str, str] | None = None,
+        require_auth: bool = True,
+    ) -> ResponseEnvelope:
+        if require_auth and not self.cfg.api_key:
+            print_error(
+                "auth_error",
+                "No Smartlead API key configured. Set SMARTLEAD_API_KEY, use --api-key, or run `smartlead config init`.",
+            )
+            raise typer.Exit(1)
+
+        merged_params: dict[str, Any] = {}
+        if params:
+            merged_params.update({k: v for k, v in params.items() if v is not None})
+        if require_auth and self.cfg.api_key:
+            merged_params.setdefault("api_key", self.cfg.api_key)
+
+        url = _resolve_url(self.cfg.base_url, path)
+        max_attempts = max(1, int(self.cfg.retries))
+
+        for attempt in range(max_attempts):
+            try:
+                with httpx.Client(timeout=self.cfg.timeout_seconds) as client:
+                    resp = client.request(method.upper(), url, params=merged_params, json=json_body, headers=headers)
+            except httpx.TimeoutException as exc:
+                if attempt < max_attempts - 1:
+                    time.sleep(min(2**attempt, 5))
+                    continue
+                print_error("timeout", f"Request timed out after {self.cfg.timeout_seconds}s", detail=str(exc))
+                raise typer.Exit(1)
+            except httpx.HTTPError as exc:
+                print_error("network_error", f"Network error: {exc}")
+                raise typer.Exit(1)
+
+            if resp.status_code in RETRYABLE_STATUS_CODES and attempt < max_attempts - 1:
+                delay = _retry_after_seconds(resp) or min(2**attempt, 5)
+                time.sleep(delay)
+                continue
+
+            if resp.status_code >= 400:
+                _handle_error_response(resp)
+                raise typer.Exit(1)
+
+            return ResponseEnvelope(status_code=resp.status_code, headers=dict(resp.headers), data=_parse_response(resp))
+
+        print_error("cli_error", "Unexpected request failure")
+        raise typer.Exit(1)
+
+
+def get_client(cfg: "Config") -> SmartleadClient:
+    return SmartleadClient(cfg)
+
+
+def api_request(
+    cfg: "Config",
+    method: str,
+    path: str,
+    *,
+    params: dict[str, Any] | None = None,
+    json_body: Any | None = None,
+    headers: dict[str, str] | None = None,
+    require_auth: bool = True,
+    include_meta: bool = False,
+) -> Any:
+    result = get_client(cfg).request(
+        method,
+        path,
+        params=params,
+        json_body=json_body,
+        headers=headers,
+        require_auth=require_auth,
+    )
+    if include_meta:
+        return {
+            "status_code": result.status_code,
+            "headers": result.headers,
+            "data": to_data(result.data),
+        }
+    return result.data
+
+
+def _resolve_url(base_url: str, path: str) -> str:
+    if path.startswith("http://") or path.startswith("https://"):
+        return path
+    base = base_url.rstrip("/") + "/"
+    rel = path.lstrip("/")
+    if rel.startswith("api/v1/"):
+        rel = rel[len("api/v1/") :]
+    return urljoin(base, rel)
+
+
+def _retry_after_seconds(resp: httpx.Response) -> int | None:
+    value = resp.headers.get("Retry-After")
+    if not value:
+        return None
+    try:
+        return max(1, int(value))
+    except ValueError:
+        return None
+
+
+def _parse_response(resp: httpx.Response) -> Any:
+    content_type = (resp.headers.get("content-type") or "").lower()
+    if "application/json" in content_type:
+        try:
+            return resp.json()
+        except Exception:
+            return {"text": resp.text}
+    if not resp.content:
+        return {"ok": True, "status_code": resp.status_code}
+    try:
+        text = resp.text
+        return {"text": text}
+    except UnicodeDecodeError:
+        return resp.content
+
+
+def _handle_error_response(resp: httpx.Response) -> None:
+    detail: Any = None
+    message = f"Smartlead API request failed ({resp.status_code})"
+    try:
+        detail = resp.json()
+        if isinstance(detail, dict):
+            message = str(detail.get("message") or detail.get("error") or message)
+    except Exception:
+        detail = resp.text[:1000] if resp.text else None
+
+    status = resp.status_code
+    if status == 401:
+        print_error("auth_error", "Authentication failed. Check SMARTLEAD_API_KEY.", status_code=status, detail=detail)
+    elif status == 403:
+        print_error("forbidden", "Permission denied.", status_code=status, detail=detail)
+    elif status == 404:
+        print_error("not_found", "Resource not found.", status_code=status, detail=detail)
+    elif status == 429:
+        print_error("rate_limit", "Rate limit exceeded.", status_code=status, detail=detail)
+    elif status == 400:
+        print_error("validation_error", message, status_code=status, detail=detail)
+    else:
+        print_error("api_error", message, status_code=status, detail=detail)

smartlead_cli-0.1.0/smartlead_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Command modules for smartlead-cli."""