cited-core 0.3.2__tar.gz

cited_core-0.3.2/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+env/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+*.so
+.coverage
+htmlcov/
+.env
+~/.cited/

cited_core-0.3.2/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: cited-core
+Version: 0.3.2
+Summary: Core library for the Cited GEO platform
+Author-email: Cited <support@youcited.com>
+License-Expression: LicenseRef-Proprietary
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: keyring>=25.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: tomli-w>=1.0.0

cited_core-0.3.2/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cited-core"
+version = "0.3.2"
+description = "Core library for the Cited GEO platform"
+license = "LicenseRef-Proprietary"
+requires-python = ">=3.11"
+authors = [{ name = "Cited", email = "support@youcited.com" }]
+dependencies = [
+    "httpx>=0.27.0",
+    "keyring>=25.0.0",
+    "tomli-w>=1.0.0",
+    "pydantic>=2.0.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cited_core"]

cited_core-0.3.2/src/cited_core/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.2"

cited_core-0.3.2/src/cited_core/api/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

cited_core-0.3.2/src/cited_core/api/client.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from cited_core.errors import CitedAPIError
+
+DEFAULT_TIMEOUT = 30.0
+LONG_TIMEOUT = 120.0
+
+
+class CitedClient:
+    def __init__(
+        self,
+        base_url: str,
+        token: str | None = None,
+        agent_api_key: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.agent_api_key = agent_api_key
+        headers: dict[str, str] = {
+            "Accept": "application/json",
+        }
+        cookies: dict[str, str] = {}
+        if token:
+            cookies["advgeo_session"] = token
+        if agent_api_key:
+            headers["X-Agent-API-Key"] = agent_api_key
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            follow_redirects=True,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> CitedClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def _handle_response(self, response: httpx.Response) -> Any:
+        if response.is_success:
+            if response.headers.get("content-type", "").startswith("application/json"):
+                return response.json()
+            return response.text
+        # Try to extract error message from JSON body
+        message = f"HTTP {response.status_code}"
+        error_code = None
+        try:
+            body = response.json()
+            if isinstance(body, dict):
+                message = str(body.get("detail", body.get("message", message)))
+                error_code = body.get("error_code")
+        except Exception:
+            message = response.text or message
+        raise CitedAPIError(response.status_code, str(message), error_code)
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        response = self._client.get(path, params=params)
+        return self._handle_response(response)
+
+    def post(
+        self,
+        path: str,
+        json: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> Any:
+        kwargs: dict[str, Any] = {}
+        if json is not None:
+            kwargs["json"] = json
+        if data is not None:
+            kwargs["data"] = data
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        response = self._client.post(path, **kwargs)
+        return self._handle_response(response)
+
+    def put(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        response = self._client.put(path, json=json or {})
+        return self._handle_response(response)
+
+    def patch(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        response = self._client.patch(path, json=json or {})
+        return self._handle_response(response)
+
+    def delete(self, path: str) -> Any:
+        response = self._client.delete(path)
+        return self._handle_response(response)
+
+    def post_raw(
+        self,
+        path: str,
+        json: dict[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> httpx.Response:
+        """POST that returns the raw httpx.Response (for cookie extraction, etc.)."""
+        kwargs: dict[str, Any] = {}
+        if json is not None:
+            kwargs["json"] = json
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        return self._client.post(path, **kwargs)

cited_core-0.3.2/src/cited_core/api/endpoints.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+# Auth
+LOGIN = "/auth/login"
+CLI_LOGIN = "/auth/cli-login"
+CLI_REGISTER = "/auth/cli-register"
+CLI_VERIFY_EMAIL = "/auth/cli-verify-email"
+CLI_OAUTH_START = "/auth/cli-oauth-start"
+LOGOUT = "/auth/logout"
+ME = "/auth/me"
+
+# System / Health
+ROOT = "/"
+HEALTH = "/health"
+HEALTH_READY = "/health/ready"
+HEALTH_LIVE = "/health/live"
+HEALTH_APIS = "/health/apis"
+
+# Business
+BUSINESSES = "/businesses"
+BUSINESS = "/businesses/{business_id}"
+BUSINESS_LOGO = "/businesses/{business_id}/logo"
+HEALTH_SCORES = "/businesses/{business_id}/health-scores"
+HEALTH_SCORES_BREAKDOWN = "/businesses/{business_id}/health-scores/breakdown"
+
+# Business Crawl
+CRAWL_DATA = "/businesses/{business_id}/crawl-data"
+CRAWL_START = "/businesses/{business_id}/crawl"
+CRAWL_CANCEL = "/businesses/{business_id}/crawl/cancel"
+
+# Named Audits (templates)
+NAMED_AUDITS = "/named-audits"
+NAMED_AUDIT = "/named-audits/{named_audit_id}"
+
+# Audit
+AUDIT_START = "/audit/start"
+AUDIT_STATUS = "/audit/{job_id}/status"
+AUDIT_RESULT = "/audit/{job_id}/result"
+AUDIT_DETAILS = "/audit/{job_id}/details"
+AUDIT_EXPORT_PDF = "/audit/{job_id}/export/pdf"
+AUDIT_HISTORY = "/audit/history"
+AUDIT_CANCEL = "/audit/{job_id}/cancel"
+AUDIT_DELETE = "/audit/{job_id}"
+AUDIT_PROVIDERS = "/audit/{job_id}/providers"
+
+# Recommendations
+RECOMMEND_START = "/recommendations/start"
+RECOMMEND_STATUS = "/recommendations/{job_id}/status"
+RECOMMEND_RESULT = "/recommendations/{job_id}/result"
+RECOMMEND_HISTORY = "/recommendations/audit/{audit_job_id}/history"
+RECOMMEND_EXPORT_PDF = "/recommendations/{job_id}/export/pdf"
+RECOMMEND_CANCEL = "/recommendations/{job_id}/cancel"
+RECOMMEND_DELETE = "/recommendations/{job_id}"
+
+# Solutions
+SOLUTION_REQUEST = "/solutions/request"
+SOLUTION_CREATE = "/solutions/create"
+SOLUTION_PRIORITY_ACTION = "/solutions/priority-action"
+SOLUTION_STATUS = "/solutions/{job_id}/status"
+SOLUTION_RESULT = "/solutions/{job_id}/result"
+SOLUTION_HISTORY = "/solutions/history"
+SOLUTION_CANCEL = "/solutions/{job_id}/cancel"
+SOLUTION_DELETE = "/solutions/{job_id}"
+
+# Business HQ
+HQ = "/businesses/{business_id}/hq"
+HQ_HEAVY = "/businesses/{business_id}/hq/heavy"
+HQ_PRIORITY = "/businesses/{business_id}/hq/priority"
+HQ_EXPORT_PDF = "/businesses/{business_id}/hq/export/pdf"
+HQ_RECOMPUTE = "/businesses/{business_id}/hq/recompute"
+PERSONAS = "/businesses/{business_id}/personas"
+PRODUCTS = "/businesses/{business_id}/products"
+BUYER_INTENTS = "/businesses/{business_id}/buyer-intents"
+AGENTIC_READINESS = "/businesses/{business_id}/agentic-readiness"
+TRUST_SIGNALS = "/businesses/{business_id}/trust-signals"
+
+# Analytics
+ANALYTICS_COMPARISON = "/analytics/audits/{audit_id}/comparison"
+ANALYTICS_SUMMARY = "/analytics/businesses/{business_id}/summary"
+ANALYTICS_TRENDS = "/analytics/businesses/{business_id}/trends"
+ANALYTICS_ADVANCED = "/analytics/businesses/{business_id}/advanced-scoring"
+
+# Agent Query API (v1)
+AGENT_ROOT = "/agent/v1"
+AGENT_BUSINESS = "/agent/v1/business/{business_id}"
+AGENT_FACTS = "/agent/v1/business/{business_id}/facts"
+AGENT_CLAIMS = "/agent/v1/business/{business_id}/claims"
+AGENT_COMPARISON = "/agent/v1/business/{business_id}/comparison"
+AGENT_SEMANTIC_HEALTH = "/agent/v1/business/{business_id}/semantic-health"
+AGENT_BUYER_FIT = "/agent/v1/query/buyer-fit"

cited_core-0.3.2/src/cited_core/auth/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

cited_core-0.3.2/src/cited_core/auth/oauth_server.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import html
+import socket
+import threading
+from functools import partial
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs, urlparse
+
+_SUCCESS_HTML_TEMPLATE = """\
+<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>Cited CLI</title>
+<style>body{{font-family:system-ui,sans-serif;display:flex;justify-content:center;
+align-items:center;height:100vh;margin:0;background:#f8f9fa;}}
+.card{{text-align:center;padding:2rem;max-width:600px;}}
+.token-section{{margin-top:1.5rem;text-align:left;}}
+.token-box{{background:#f1f5f9;border:1px solid #cbd5e1;border-radius:6px;
+padding:0.75rem;font-family:monospace;font-size:0.8rem;word-break:break-all;
+max-height:4rem;overflow-y:auto;}}
+.copy-btn{{margin-top:0.5rem;padding:0.4rem 1rem;background:#3b82f6;color:#fff;
+border:none;border-radius:4px;cursor:pointer;font-size:0.85rem;}}
+.copy-btn:hover{{background:#2563eb;}}</style></head>
+<body><div class="card">
+<h1 style="color:#22c55e;">&#10003; Authentication successful</h1>
+<p>You can close this tab and return to your terminal.</p>
+<details class="token-section">
+<summary>Terminal not responding? Copy your token manually</summary>
+<p style="font-size:0.85rem;color:#475569;">
+If the CLI didn't detect the login, copy this token and paste it in your terminal.</p>
+<div class="token-box" id="token-text">{token}</div>
+<button class="copy-btn" onclick="
+var t=document.getElementById('token-text').textContent;
+navigator.clipboard.writeText(t).then(function(){{this.textContent='Copied!'}}.bind(this))
+">Copy token</button>
+</details>
+</div></body></html>
+"""
+
+_ERROR_HTML = """\
+<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>Cited CLI</title>
+<style>body{font-family:system-ui,sans-serif;display:flex;justify-content:center;
+align-items:center;height:100vh;margin:0;background:#f8f9fa;}
+.card{text-align:center;padding:2rem;}</style></head>
+<body><div class="card">
+<h1 style="color:#ef4444;">Authentication failed</h1>
+<p>No token was received. Please try again.</p>
+</div></body></html>
+"""
+
+
+def _find_free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        port: int = s.getsockname()[1]
+        return port
+
+
+class _CallbackHandler(BaseHTTPRequestHandler):
+    def __init__(  # type: ignore[no-untyped-def]
+        self, token_event: threading.Event, server_ref: OAuthCallbackServer, *args, **kwargs,
+    ):
+        self._token_event = token_event
+        self._server_ref = server_ref
+        super().__init__(*args, **kwargs)
+
+    def do_GET(self) -> None:  # noqa: N802
+        parsed = urlparse(self.path)
+        if parsed.path != "/callback":
+            self.send_error(404)
+            return
+
+        params = parse_qs(parsed.query)
+        token = params.get("token", [None])[0]
+
+        if token:
+            self._server_ref.token = token
+            success_html = _SUCCESS_HTML_TEMPLATE.format(token=html.escape(token))
+            self._send_html(200, success_html)
+            self._token_event.set()
+        else:
+            self._send_html(400, _ERROR_HTML)
+
+    def _send_html(self, code: int, html: str) -> None:
+        self.send_response(code)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.end_headers()
+        self.wfile.write(html.encode())
+
+    def log_message(self, format: str, *args: object) -> None:  # noqa: A002
+        pass  # Suppress request logging
+
+
+class OAuthCallbackServer:
+    """Temporary localhost server to receive OAuth callback with token."""
+
+    def __init__(self, timeout: float = 120.0) -> None:
+        self.token: str | None = None
+        self.port: int = _find_free_port()
+        self.redirect_uri = f"http://localhost:{self.port}/callback"
+        self._timeout = timeout
+        self._token_event = threading.Event()
+        self._server: HTTPServer | None = None
+        self._thread: threading.Thread | None = None
+
+    def start(self) -> None:
+        handler = partial(_CallbackHandler, self._token_event, self)
+        self._server = HTTPServer(("127.0.0.1", self.port), handler)
+        self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
+        self._thread.start()
+
+    def wait_for_token(self) -> str | None:
+        self._token_event.wait(timeout=self._timeout)
+        return self.token
+
+    def shutdown(self) -> None:
+        if self._server:
+            self._server.shutdown()
+        if self._thread:
+            self._thread.join(timeout=5)

cited_core-0.3.2/src/cited_core/auth/store.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import stat
+
+from cited_core.config.constants import CONFIG_DIR, CREDENTIALS_FILE, KEYRING_SERVICE
+
+
+class TokenStore:
+    def __init__(self) -> None:
+        self._keyring_available: bool | None = None
+
+    def _has_keyring(self) -> bool:
+        if self._keyring_available is None:
+            try:
+                import keyring
+                from keyring.backends.fail import Keyring as FailKeyring
+
+                backend = keyring.get_keyring()
+                self._keyring_available = not isinstance(backend, FailKeyring)
+            except Exception:
+                self._keyring_available = False
+        return self._keyring_available
+
+    def save_token(self, env: str, token: str) -> None:
+        if self._has_keyring():
+            import keyring
+
+            keyring.set_password(KEYRING_SERVICE, f"token:{env}", token)
+        else:
+            self._save_file(env, token)
+
+    def get_token(self, env: str) -> str | None:
+        if self._has_keyring():
+            import keyring
+
+            return keyring.get_password(KEYRING_SERVICE, f"token:{env}")
+        return self._load_file(env)
+
+    def delete_token(self, env: str) -> None:
+        if self._has_keyring():
+            import keyring
+
+            with contextlib.suppress(keyring.errors.PasswordDeleteError):
+                keyring.delete_password(KEYRING_SERVICE, f"token:{env}")
+        else:
+            self._delete_file(env)
+
+    def has_token(self, env: str) -> bool:
+        return self.get_token(env) is not None
+
+    # --- file fallback ---
+
+    def _ensure_creds_file(self) -> dict[str, str]:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        if CREDENTIALS_FILE.exists():
+            with open(CREDENTIALS_FILE) as f:
+                data: dict[str, str] = json.load(f)
+                return data
+        return {}
+
+    def _write_creds(self, data: dict[str, str]) -> None:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        with open(CREDENTIALS_FILE, "w") as f:
+            json.dump(data, f, indent=2)
+        os.chmod(CREDENTIALS_FILE, stat.S_IRUSR | stat.S_IWUSR)
+
+    def _save_file(self, env: str, token: str) -> None:
+        data = self._ensure_creds_file()
+        data[env] = token
+        self._write_creds(data)
+
+    def _load_file(self, env: str) -> str | None:
+        data = self._ensure_creds_file()
+        return data.get(env)
+
+    def _delete_file(self, env: str) -> None:
+        data = self._ensure_creds_file()
+        if env in data:
+            del data[env]
+            self._write_creds(data)

cited_core-0.3.2/src/cited_core/config/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

cited_core-0.3.2/src/cited_core/config/constants.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+ENVIRONMENTS: dict[str, str] = {
+    "prod": "https://api.youcited.com",
+    "dev": "https://dev.youcited.com",
+    "local": "http://localhost:8000",
+}
+
+FRONTEND_URLS: dict[str, str] = {
+    "prod": "https://app.youcited.com",
+    "dev": "https://dev.youcited.com",
+    "local": "http://localhost:3000",
+}
+
+DEFAULT_ENV = "prod"
+CONFIG_DIR = Path.home() / ".cited"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+CREDENTIALS_FILE = CONFIG_DIR / "credentials.json"
+KEYRING_SERVICE = "cited-cli"
+
+VALID_INDUSTRIES = [
+    "automotive",
+    "beauty",
+    "consulting",
+    "education",
+    "entertainment",
+    "finance",
+    "fitness",
+    "government",
+    "healthcare",
+    "home_services",
+    "hospitality",
+    "legal",
+    "manufacturing",
+    "non_profit",
+    "real_estate",
+    "restaurant",
+    "retail",
+    "technology",
+    "other",
+]
+
+VALID_SOURCE_TYPES = [
+    "question_insight",
+    "head_to_head",
+    "strengthening_tip",
+    "priority_action",
+]

cited_core-0.3.2/src/cited_core/config/manager.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import tomllib
+from typing import Any
+
+import tomli_w
+
+from cited_core.config.constants import CONFIG_DIR, CONFIG_FILE, DEFAULT_ENV, ENVIRONMENTS
+
+VALID_KEYS = {
+    "environment",
+    "default_business_id",
+    "agent_api_key",
+    "output",
+}
+
+VALID_OUTPUT_VALUES = {"json", "text"}
+
+
+class ConfigManager:
+    def __init__(self) -> None:
+        self._ensure_config_dir()
+        self._data: dict[str, Any] = self._load()
+
+    def _ensure_config_dir(self) -> None:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+    def _load(self) -> dict[str, Any]:
+        if not CONFIG_FILE.exists():
+            return {"default": {}}
+        with open(CONFIG_FILE, "rb") as f:
+            return tomllib.load(f)
+
+    def _save(self) -> None:
+        with open(CONFIG_FILE, "wb") as f:
+            tomli_w.dump(self._data, f)
+
+    def get(self, key: str, profile: str = "default") -> Any:
+        section = self._data.get(profile, self._data.get("default", {}))
+        return section.get(key)
+
+    def set(self, key: str, value: str, profile: str = "default") -> None:
+        if profile not in self._data:
+            self._data[profile] = {}
+        self._data[profile][key] = value
+        self._save()
+
+    def delete(self, key: str, profile: str = "default") -> bool:
+        section = self._data.get(profile, {})
+        if key in section:
+            del section[key]
+            self._save()
+            return True
+        return False
+
+    def get_all(self, profile: str = "default") -> dict[str, Any]:
+        return dict(self._data.get(profile, {}))
+
+    def get_environment(self, profile: str = "default", override: str | None = None) -> str:
+        if override:
+            return override
+        return self.get("environment", profile) or DEFAULT_ENV
+
+    def get_api_url(self, profile: str = "default", env_override: str | None = None) -> str:
+        env = self.get_environment(profile, env_override)
+        return ENVIRONMENTS.get(env, ENVIRONMENTS[DEFAULT_ENV])
+
+    def get_profiles(self) -> list[str]:
+        return [k for k in self._data if k != "default" and isinstance(self._data[k], dict)]

cited_core-0.3.2/src/cited_core/errors.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    SUCCESS = 0
+    ERROR = 1
+    AUTH_ERROR = 2
+    NOT_FOUND = 3
+    VALIDATION_ERROR = 4
+    RATE_LIMITED = 5
+
+
+class CitedAPIError(Exception):
+    def __init__(self, status_code: int, message: str, error_code: str | None = None):
+        self.status_code = status_code
+        self.message = message
+        self.error_code = error_code
+        super().__init__(message)
+
+
+def exit_code_for_status(status_code: int) -> ExitCode:
+    if status_code == 401 or status_code == 403:
+        return ExitCode.AUTH_ERROR
+    if status_code == 404:
+        return ExitCode.NOT_FOUND
+    if status_code == 422:
+        return ExitCode.VALIDATION_ERROR
+    if status_code == 429:
+        return ExitCode.RATE_LIMITED
+    return ExitCode.ERROR