dogfu 0.4.0__tar.gz

dogfu-0.4.0/.env.example

@@ -0,0 +1,12 @@
+# dogfu configuration.
+#
+# Auth is a single dogfu session token. The normal way to set it is:
+#   dogfu configure --otp <OTP> --title "<what this session is for>"
+# which writes it to ~/.dogfu/config.json. The variables below are optional
+# overrides (export them, or copy this file to .env and source it).
+
+# Overrides the saved session token (takes precedence over ~/.dogfu/config.json).
+# DOGFU_TOKEN=eyJ...
+
+# Overrides the backend API root (for local/staging). Defaults to the prod URL.
+# DOGFU_BASE_URL=https://backend.agentberlin.ai

dogfu-0.4.0/.gitignore

@@ -0,0 +1,8 @@
+.env
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.uv/

dogfu-0.4.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: dogfu
+Version: 0.4.0
+Summary: Internal admin/marketing CLI — discovery, enrichment, outreach, and CRM over one interface.
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: requests>=2.31
+Requires-Dist: rich>=13.7
+Provides-Extra: dev
+Requires-Dist: black>=24.0.0; extra == 'dev'
+Requires-Dist: isort>=5.13.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: responses>=0.25.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dogfu
+
+Internal admin CLI + SDK for Agent Berlin staff (`admin_users`). One
+interface over LinkedIn, X, Google, ChatGPT, SEO (the dogfu data API) and the
+Close CRM (via the admin CRM proxy). The sibling of `backend/sdk-python` — same
+transport posture (a single Bearer token against the Berlin backend, retry with
+backoff, a typed exception hierarchy, config-file session), scoped to the
+internal admin surface instead of a customer project.
+
+## Auth
+
+dogfu authenticates with a single **session token** (a short-lived JWT, 24h),
+minted by exchanging a one-time OTP from the dogfu MCP's `get_setup_instructions`:
+
+```bash
+dogfu configure --otp <OTP> --title "<what this session is for>"
+```
+
+This `POST`s `{otp, title}` to `/dogfucli/exchange-otp` and saves the returned
+token to `~/.dogfu/config.json`. Subsequent commands resolve the token from
+`DOGFU_TOKEN` first, then that file. There is no refresh endpoint — on an auth
+failure, run `get_setup_instructions` again for a fresh OTP and re-`configure`.
+
+dogfu is **not project-scoped** (no `--domain`); access is platform-wide for
+staff.
+
+## Endpoints
+
+Everything goes through the Berlin backend (`https://backend.agentberlin.ai` by
+default; override with `--base-url` / `DOGFU_BASE_URL`):
+
+| Group | Backend route |
+| --- | --- |
+| `linkedin` / `x` / `google` / `chatgpt` / `seo` | `/api/v1/admin/dogfu/*` |
+| `crm` | `/api/v1/admin/crm/*` — allowlisted proxy to Close CRM |
+
+The CRM proxy holds the per-admin Close key server-side (configured from the
+admin Console), so dogfu never sees a Close credential — it forwards Close
+sub-paths under the dogfu session token.
+
+## Usage
+
+```bash
+dogfu --help                  # list groups
+dogfu <group> --help          # list a group's commands
+dogfu <group> <cmd> --help    # flags + the Output: data shape
+
+dogfu seo domain-overview --target acme.com
+dogfu crm lead create --name "Acme" --url https://acme.com
+```
+
+Output is canonical JSON by default (`-f table` for humans, `-o FILE` to write).
+
+## Programmatic use
+
+```python
+from dogfu import Dogfu
+dx = Dogfu()                                  # resolves DOGFU_TOKEN / config file
+dx.seo.domain_overview(target="acme.com")     # -> DomainOverview
+dx.crm.create_lead(name="Acme")
+```
+
+## Develop
+
+```bash
+uv run python tests/smoke.py   # offline checks (normalizers, models, SDK wiring)
+```

dogfu-0.4.0/README.md

@@ -0,0 +1,67 @@
+# dogfu
+
+Internal admin CLI + SDK for Agent Berlin staff (`admin_users`). One
+interface over LinkedIn, X, Google, ChatGPT, SEO (the dogfu data API) and the
+Close CRM (via the admin CRM proxy). The sibling of `backend/sdk-python` — same
+transport posture (a single Bearer token against the Berlin backend, retry with
+backoff, a typed exception hierarchy, config-file session), scoped to the
+internal admin surface instead of a customer project.
+
+## Auth
+
+dogfu authenticates with a single **session token** (a short-lived JWT, 24h),
+minted by exchanging a one-time OTP from the dogfu MCP's `get_setup_instructions`:
+
+```bash
+dogfu configure --otp <OTP> --title "<what this session is for>"
+```
+
+This `POST`s `{otp, title}` to `/dogfucli/exchange-otp` and saves the returned
+token to `~/.dogfu/config.json`. Subsequent commands resolve the token from
+`DOGFU_TOKEN` first, then that file. There is no refresh endpoint — on an auth
+failure, run `get_setup_instructions` again for a fresh OTP and re-`configure`.
+
+dogfu is **not project-scoped** (no `--domain`); access is platform-wide for
+staff.
+
+## Endpoints
+
+Everything goes through the Berlin backend (`https://backend.agentberlin.ai` by
+default; override with `--base-url` / `DOGFU_BASE_URL`):
+
+| Group | Backend route |
+| --- | --- |
+| `linkedin` / `x` / `google` / `chatgpt` / `seo` | `/api/v1/admin/dogfu/*` |
+| `crm` | `/api/v1/admin/crm/*` — allowlisted proxy to Close CRM |
+
+The CRM proxy holds the per-admin Close key server-side (configured from the
+admin Console), so dogfu never sees a Close credential — it forwards Close
+sub-paths under the dogfu session token.
+
+## Usage
+
+```bash
+dogfu --help                  # list groups
+dogfu <group> --help          # list a group's commands
+dogfu <group> <cmd> --help    # flags + the Output: data shape
+
+dogfu seo domain-overview --target acme.com
+dogfu crm lead create --name "Acme" --url https://acme.com
+```
+
+Output is canonical JSON by default (`-f table` for humans, `-o FILE` to write).
+
+## Programmatic use
+
+```python
+from dogfu import Dogfu
+dx = Dogfu()                                  # resolves DOGFU_TOKEN / config file
+dx.seo.domain_overview(target="acme.com")     # -> DomainOverview
+dx.crm.create_lead(name="Acme")
+```
+
+## Develop
+
+```bash
+uv run python tests/smoke.py   # offline checks (normalizers, models, SDK wiring)
+```

dogfu-0.4.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "dogfu"
+version = "0.4.0"
+description = "Internal admin/marketing CLI — discovery, enrichment, outreach, and CRM over one interface."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "click>=8.1",
+    "requests>=2.31",
+    "rich>=13.7",
+]
+
+[project.scripts]
+dogfu = "dogfu.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dogfu"]
+
+[project.optional-dependencies]
+dev = [
+    "black>=24.0.0",
+    "isort>=5.13.0",
+    "pytest>=8.0.0",
+    "responses>=0.25.0",
+]
+
+[tool.black]
+line-length = 100
+
+[tool.isort]
+profile = "black"
+line_length = 100
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

dogfu-0.4.0/src/dogfu/__init__.py

@@ -0,0 +1,58 @@
+"""dogfu — internal admin tooling (LinkedIn, X, Google, ChatGPT, SEO, Close CRM)
+as one CLI and one importable SDK.
+
+Each command/method is a thin, direct wrapper over a single backend capability and
+returns a canonical dataclass model (so the same layer is usable from a program, not
+just the shell). It is deliberately *not* organized around sales phases — composing
+these tools into a workflow is the caller's (or the agent prompt's) job.
+
+Auth is a single dogfu session token, minted by `dogfu configure` and resolved
+from `DOGFU_TOKEN` or `~/.dogfu/config.json`. Every call (dogfu data API + CRM
+proxy) goes through the Agent Berlin backend over Bearer auth.
+
+Programmatic use:
+
+    from dogfu import Dogfu
+    dx = Dogfu()
+    dx.seo.domain_overview(target="acme.com")     # -> DomainOverview
+
+Layering: providers (raw transport) → normalize (dict→model) → models (the contract)
+→ sdk (typed clients) → client.Dogfu (facade) → commands (CLI).
+"""
+
+# Defined before the imports below so modules that read it during import
+# (e.g. providers.http's User-Agent) see a populated value.
+__version__ = "0.4.0"
+
+from .client import Dogfu
+from .config import Config, RetryConfig
+from .exceptions import (
+    ConfigError,
+    CustomFieldError,
+    DogfuAPIError,
+    DogfuAuthenticationError,
+    DogfuConnectionError,
+    DogfuError,
+    DogfuNotFoundError,
+    DogfuRateLimitError,
+    DogfuServerError,
+)
+from .session import configure_session, load_session_config
+
+__all__ = [
+    "Dogfu",
+    "Config",
+    "RetryConfig",
+    "configure_session",
+    "load_session_config",
+    "DogfuError",
+    "ConfigError",
+    "CustomFieldError",
+    "DogfuAPIError",
+    "DogfuAuthenticationError",
+    "DogfuConnectionError",
+    "DogfuNotFoundError",
+    "DogfuRateLimitError",
+    "DogfuServerError",
+    "__version__",
+]

dogfu-0.4.0/src/dogfu/__main__.py

@@ -0,0 +1,6 @@
+"""Enable `python -m dogfu`."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

dogfu-0.4.0/src/dogfu/cli.py

@@ -0,0 +1,113 @@
+"""dogfu — internal admin tooling as one CLI.
+
+Each group wraps one backend capability and prints a canonical JSON object (see
+that command's --help for its exact `Output:` shape). Composing these into a
+workflow is the caller's job, not the tool's.
+
+\b
+Setup
+  Auth is a single dogfu session token. Get an OTP from the dogfu MCP's
+  get_setup_instructions, then run:
+    dogfu configure --otp <OTP> --title "<what this session is for>"
+  The token is saved to ~/.dogfu/config.json (override with DOGFU_TOKEN).
+
+\b
+Discovery
+  dogfu --help                 list groups
+  dogfu <group> --help         list a group's commands
+  dogfu <group> <cmd> --help   full flags + the Output: data shape
+
+\b
+Output
+  Canonical JSON by default; -f table for humans; -o FILE to write to a file.
+
+\b
+Programmatic use
+  from dogfu import Dogfu; Dogfu().seo.domain_overview(target="acme.com")
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Optional
+
+import click
+import requests
+
+from . import __version__
+from .commands import chatgpt, crm, google, linkedin, seo, x
+from .config import resolve_base_url
+from .exceptions import DogfuError
+from .session import configure_session
+
+
+@click.group(help=__doc__)
+@click.version_option(version=__version__, prog_name="dogfu")
+def cli() -> None:
+    pass
+
+
+for _group in (linkedin, x, google, chatgpt, seo, crm):
+    cli.add_command(_group)
+
+
+@cli.command(hidden=True)
+@click.option("--otp", required=True, help="One-time password from the dogfu MCP get_setup_instructions response.")
+@click.option("--title", required=True, help="Short description of what this session is for.")
+@click.option("--config-path", hidden=True, help="Custom config file path.")
+@click.option("--base-url", default=None, hidden=True)
+def configure(otp: str, title: str, config_path: Optional[str], base_url: Optional[str]) -> None:
+    """Exchange a dogfu OTP for a session token and persist it for later commands.
+
+    Hidden by design: invoked by the dogfu MCP bootstrap flow, not typed by humans.
+    """
+    # dogfu's base URL is the API root (no /sdk suffix), so POST directly.
+    root = resolve_base_url(base_url)
+    exchange_url = f"{root}/dogfucli/exchange-otp"
+
+    try:
+        resp = requests.post(
+            exchange_url,
+            json={"otp": otp, "title": title},
+            timeout=30,
+        )
+    except requests.RequestException as e:
+        raise click.ClickException(f"Failed to reach exchange endpoint: {e}")
+
+    if resp.status_code != 200:
+        # Surface the server's message verbatim (Echo returns {"message": "..."}),
+        # falling back to text/reason.
+        try:
+            body = resp.json()
+            detail = body.get("message") or body.get("error") or resp.text
+        except ValueError:
+            detail = resp.text or resp.reason
+        raise click.ClickException(f"OTP exchange failed ({resp.status_code}): {detail}")
+
+    token = resp.json().get("token")
+    if not token:
+        raise click.ClickException("Exchange response did not include a token.")
+
+    path = configure_session(token, config_path=config_path)
+    click.echo(f"dogfu session configured. Token saved to {path}.")
+
+
+def main() -> None:
+    """CLI entrypoint. Renders DogfuError (SDK/transport errors) as a clean
+    one-line message instead of a traceback, while letting click handle its own
+    usage/help/version flow."""
+    try:
+        cli.main(standalone_mode=False, prog_name="dogfu")
+    except click.ClickException as e:
+        e.show()
+        sys.exit(e.exit_code)
+    except click.exceptions.Abort:
+        click.echo("Aborted!", err=True)
+        sys.exit(1)
+    except DogfuError as e:
+        click.echo(click.style(f"Error: {e}", fg="red"), err=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

dogfu-0.4.0/src/dogfu/client.py

@@ -0,0 +1,108 @@
+"""The Dogfu facade — the entry point for both the CLI and programmatic use.
+
+    from dogfu import Dogfu
+    dx = Dogfu()                                   # resolves the session token lazily
+    profiles = dx.linkedin.profiles(urls=[url])    # -> list[LinkedInProfile]
+    overview = dx.seo.domain_overview(target="acme.com")
+    lead = dx.crm.create_lead(name="Acme")
+
+One Bearer-authenticated transport (the dogfu session token) backs everything:
+the dogfu data API and the CRM proxy. The transport is built lazily, so
+constructing `Dogfu` never resolves credentials — only touching a provider does,
+which is what lets `dogfu configure` (and `--help`) run without a token. The raw
+transports are also exposed (`dx.dogfu`, `dx.close`) for the rare case you
+want the untouched provider payload.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .config import Config, resolve_base_url, resolve_token
+from .providers import CloseClient, DogfuClient
+from .providers.http import HTTPClient
+from .sdk import (
+    ChatGPTClient,
+    CrmClient,
+    GoogleClient,
+    LinkedInClient,
+    SeoClient,
+    XClient,
+)
+
+
+class Dogfu:
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        base_url: Optional[str] = None,
+        config: Optional[Config] = None,
+        config_path: Optional[str] = None,
+    ) -> None:
+        self._config = config or Config(base_url=resolve_base_url(base_url))
+        self._token = token
+        self._config_path = config_path
+        self._http: Optional[HTTPClient] = None
+        self._dogfu: Optional[DogfuClient] = None
+        self._close: Optional[CloseClient] = None
+        self._crm: Optional[CrmClient] = None
+
+    @property
+    def config(self) -> Config:
+        return self._config
+
+    # The shared transport. Lazily resolves the token (env -> config file) and
+    # builds one Bearer-authenticated client reused by every provider.
+    @property
+    def http(self) -> HTTPClient:
+        if self._http is None:
+            token = resolve_token(self._token, self._config_path)
+            self._http = HTTPClient(
+                token,
+                self._config.base_url,
+                timeout=self._config.timeout,
+                retry_config=self._config.retry,
+            )
+        return self._http
+
+    # Raw transports (lazy; resolve credentials on first use).
+    @property
+    def dogfu(self) -> DogfuClient:
+        if self._dogfu is None:
+            self._dogfu = DogfuClient(self.http)
+        return self._dogfu
+
+    @property
+    def close(self) -> CloseClient:
+        if self._close is None:
+            self._close = CloseClient(self.http)
+        return self._close
+
+    # Typed clients (return models).
+    @property
+    def linkedin(self) -> LinkedInClient:
+        return LinkedInClient(self.dogfu)
+
+    @property
+    def x(self) -> XClient:
+        return XClient(self.dogfu)
+
+    @property
+    def google(self) -> GoogleClient:
+        return GoogleClient(self.dogfu)
+
+    @property
+    def chatgpt(self) -> ChatGPTClient:
+        return ChatGPTClient(self.dogfu)
+
+    @property
+    def seo(self) -> SeoClient:
+        return SeoClient(self.dogfu)
+
+    @property
+    def crm(self) -> CrmClient:
+        # Memoized: the CRM client caches the custom-field schema, so reusing one
+        # instance keeps curated-field reads/writes to a single schema fetch.
+        if self._crm is None:
+            self._crm = CrmClient(self.close)
+        return self._crm

dogfu-0.4.0/src/dogfu/commands/__init__.py

@@ -0,0 +1,10 @@
+"""CLI command groups — one per provider/resource, flat. No workflow abstraction."""
+
+from .chatgpt import chatgpt
+from .crm import crm
+from .google import google
+from .linkedin import linkedin
+from .seo import seo
+from .x import x_group as x
+
+__all__ = ["linkedin", "x", "google", "chatgpt", "seo", "crm"]

dogfu-0.4.0/src/dogfu/commands/_shared.py

@@ -0,0 +1,69 @@
+"""Shared plumbing for the command layer.
+
+`AppContext` lazily builds the Dogfu facade. `output_options` attaches the
+universal output flags. `--raw` exists (returns the untouched provider payload) but
+is **hidden** — it isn't shown in `--help` and isn't part of the documented surface,
+so agents work with the canonical models by default.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable, Optional
+
+import click
+
+from ..client import Dogfu
+
+
+class AppContext:
+    def __init__(self) -> None:
+        self._sx: Optional[Dogfu] = None
+
+    @property
+    def sx(self) -> Dogfu:
+        if self._sx is None:
+            self._sx = Dogfu()
+        return self._sx
+
+
+pass_app = click.make_pass_decorator(AppContext, ensure=True)
+
+
+def output_options(func: Callable) -> Callable:
+    """Attach -f/--format, -o/--output, and a hidden --raw to a leaf command."""
+    func = click.option(
+        "-o", "--output", "output",
+        type=click.Path(dir_okay=False, writable=True),
+        help="Write JSON to this file instead of stdout.",
+    )(func)
+    func = click.option(
+        "--raw", is_flag=True, hidden=True,
+        help="Internal: emit the untouched provider payload (undocumented).",
+    )(func)
+    func = click.option(
+        "-f", "--format", "fmt",
+        type=click.Choice(["json", "table"]), default="json", show_default=True,
+        help="Output format.",
+    )(func)
+    return func
+
+
+def split_name(full: str) -> dict[str, str]:
+    """Split 'First Middle Last' into {first_name, last_name}."""
+    parts = full.strip().split()
+    if not parts:
+        raise click.UsageError("Empty name.")
+    if len(parts) == 1:
+        return {"first_name": parts[0], "last_name": ""}
+    return {"first_name": parts[0], "last_name": " ".join(parts[1:])}
+
+
+def parse_filters(filters: Optional[str]) -> Any:
+    """Parse a --filters value as JSON, falling back to the raw string."""
+    if filters is None:
+        return None
+    try:
+        return json.loads(filters)
+    except json.JSONDecodeError:
+        return filters

dogfu-0.4.0/src/dogfu/commands/chatgpt.py

@@ -0,0 +1,48 @@
+"""`dogfu chatgpt ...` — web-grounded ChatGPT answer with citations."""
+
+from __future__ import annotations
+
+import click
+
+from ..output import emit
+from ._shared import output_options, pass_app
+
+
+@click.group()
+def chatgpt() -> None:
+    """Web-grounded ChatGPT answers with citations."""
+
+
+@chatgpt.command("search")
+@click.option("--query", required=True, help="The question.")
+@click.option("--model", help="gpt-5.5 | gpt-5.4-mini | gpt-5.4-nano (default gpt-5.4-mini).")
+@click.option("--system-prompt", help="Optional system instructions.")
+@click.option("--search-context-size", type=click.Choice(["low", "medium", "high"]), help="Grounding context size.")
+@click.option("--domain-filter", "domain_filter", multiple=True, help="Restrict grounding to this domain (repeatable).")
+@click.option("--max-tokens", type=int, help="Cap response length.")
+@click.option("--reasoning-effort", type=click.Choice(["minimal", "low", "medium", "high"]), help="Reasoning effort.")
+@click.option("--include-citations/--no-include-citations", "include_citations", default=None, help="Include citations (default true).")
+@click.option("--city", help="user_location.city")
+@click.option("--region", help="user_location.region")
+@click.option("--user-country", help="user_location.country")
+@click.option("--timezone", help="user_location.timezone")
+@output_options
+@pass_app
+def search(app, query, model, system_prompt, search_context_size, domain_filter,
+           max_tokens, reasoning_effort, include_citations, city, region,
+           user_country, timezone, fmt, raw, output):
+    """Ask ChatGPT a question with live web grounding.
+
+    Output: AnswerResult — query, engine ("chatgpt"), model, answer (text),
+    citations[] (title, url, snippet), usage{input_tokens, output_tokens,
+    total_tokens}.
+    """
+    user_location = {k: v for k, v in {
+        "city": city, "region": region, "country": user_country, "timezone": timezone,
+    }.items() if v is not None} or None
+    kw = dict(query=query, model=model, system_prompt=system_prompt,
+              search_context_size=search_context_size, domain_filter=list(domain_filter) or None,
+              max_tokens=max_tokens, reasoning_effort=reasoning_effort,
+              include_citations=include_citations, user_location=user_location)
+    data = app.sx.dogfu.chatgpt_search(**kw) if raw else app.sx.chatgpt.search(**kw)
+    emit(data, fmt=fmt, raw=raw, output=output, title="ChatGPT")