loxo-cli 0.1.0__py3-none-any.whl

loxo_cli/__init__.py

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

loxo_cli/__main__.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+import typer
+from rich.console import Console
+
+from loxo_cli import __version__
+from loxo_cli.client import LoxoClient, build_client
+from loxo_cli.commands._app import LoxoGroup
+from loxo_cli.config import LoxoSettings, load_settings
+from loxo_cli.output import render
+
+HELP_EPILOG = "Unofficial — not affiliated with Loxo, Inc."
+
+app = typer.Typer(
+    cls=LoxoGroup,
+    help="loxo — command-line interface for the Loxo recruiting API.",
+    epilog=HELP_EPILOG,
+    no_args_is_help=True,
+)
+
+
+@dataclass
+class AppState:
+    profile: Optional[str]
+    api_key: Optional[str]
+    slug: Optional[str]
+    base_url: Optional[str]
+    json_out: bool
+    jq: Optional[str]
+    verbose: bool
+    no_color: bool
+    config_path: Optional[Path] = None
+    _settings: Optional[LoxoSettings] = field(default=None, repr=False)
+
+    def settings(self) -> LoxoSettings:
+        if self._settings is None:
+            self._settings = load_settings(
+                profile=self.profile,
+                api_key=self.api_key,
+                slug=self.slug,
+                base_url=self.base_url,
+                config_path=self.config_path,
+            )
+        return self._settings
+
+    def client(self) -> LoxoClient:
+        return build_client(self.settings(), verbose=self.verbose)
+
+    def console(self) -> Console:
+        return Console(no_color=self.no_color)
+
+    def emit(self, data: Any, *, columns: list[str] | None = None) -> None:
+        render(
+            data,
+            as_json=self.json_out,
+            jq=self.jq,
+            columns=columns,
+            console=self.console(),
+        )
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False, "--version", callback=_version_callback, is_eager=True, help="Show version and exit."
+    ),
+    profile: Optional[str] = typer.Option(None, "--profile", help="Config profile."),
+    api_key: Optional[str] = typer.Option(None, "--api-key", help="Loxo API key."),
+    slug: Optional[str] = typer.Option(None, "--slug", help="Agency slug."),
+    base_url: Optional[str] = typer.Option(None, "--base-url", help="API base URL."),
+    json_out: bool = typer.Option(False, "--json", help="Force JSON output."),
+    jq: Optional[str] = typer.Option(None, "--jq", help="Filter output (dotted path)."),
+    quiet: bool = typer.Option(False, "--quiet", help="Suppress non-error output."),
+    verbose: bool = typer.Option(False, "-v", "--verbose", help="Log requests to stderr."),
+    no_color: bool = typer.Option(False, "--no-color", help="Disable color."),
+) -> None:
+    """loxo CLI. Unofficial — not affiliated with Loxo, Inc."""
+    ctx.obj = AppState(
+        profile=profile,
+        api_key=api_key,
+        slug=slug,
+        base_url=base_url,
+        json_out=json_out,
+        jq=jq,
+        verbose=verbose,
+        no_color=no_color,
+    )
+
+
+from loxo_cli.commands import api as _api_cmd  # noqa: E402
+from loxo_cli.commands.activities import activities_app  # noqa: E402
+from loxo_cli.commands.candidates import candidates_app  # noqa: E402
+from loxo_cli.commands.companies import companies_app  # noqa: E402
+from loxo_cli.commands.configure import configure_app  # noqa: E402
+from loxo_cli.commands.deals import deals_app  # noqa: E402
+from loxo_cli.commands.jobs import jobs_app  # noqa: E402
+from loxo_cli.commands.people import people_app  # noqa: E402
+from loxo_cli.commands.ref import ref_app  # noqa: E402
+from loxo_cli.commands.webhooks import webhooks_app  # noqa: E402
+
+_api_cmd.register(app)
+app.add_typer(configure_app, name="configure")
+app.add_typer(people_app, name="people")
+app.add_typer(jobs_app, name="jobs")
+app.add_typer(companies_app, name="companies")
+app.add_typer(deals_app, name="deals")
+app.add_typer(candidates_app, name="candidates")
+app.add_typer(activities_app, name="activities")
+app.add_typer(webhooks_app, name="webhooks")
+app.add_typer(ref_app, name="ref")
+
+
+def run() -> None:
+    # Exit-code mapping happens in LoxoGroup.invoke (commands/_app.py, set via
+    # typer.Typer(cls=LoxoGroup)): Typer does NOT honor a raised ClickException's
+    # exit_code, so domain errors become typer.Exit with the mapped code.
+    app()
+
+
+if __name__ == "__main__":
+    run()

loxo_cli/client.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import sys
+from typing import Any, Mapping
+
+import httpx
+
+from loxo_cli.config import LoxoSettings
+from loxo_cli.errors import LoxoError
+
+TIMEOUT = 30.0
+
+
+def url_for(settings: LoxoSettings, endpoint: str) -> str:
+    return f"{settings.base_url}/{settings.slug}/{endpoint.lstrip('/')}"
+
+
+class LoxoClient:
+    def __init__(self, settings: LoxoSettings, *, verbose: bool = False) -> None:
+        self._settings = settings
+        self._verbose = verbose
+        self._http = httpx.Client(
+            headers={
+                "Authorization": f"Bearer {settings.api_key}",
+                "Accept": "application/json",
+            },
+            follow_redirects=True,
+            timeout=TIMEOUT,
+        )
+
+    def __enter__(self) -> "LoxoClient":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def request(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any | None = None,
+    ) -> Any:
+        target = url_for(self._settings, endpoint)
+        if self._verbose:
+            # Method + URL only. Never headers (would leak the bearer token).
+            print(f"{method.upper()} {target}", file=sys.stderr)
+        headers = {"Content-Type": "application/json"} if json is not None else None
+        try:
+            response = self._http.request(method, target, params=params, json=json, headers=headers)
+            response.raise_for_status()
+        except httpx.TimeoutException as exc:
+            raise LoxoError(
+                f"Loxo {method} {endpoint} timed out", status_code=None, is_timeout=True
+            ) from exc
+        except httpx.HTTPStatusError as exc:
+            raise LoxoError(
+                f"Loxo {method} {endpoint} returned {exc.response.status_code}: "
+                f"{exc.response.text[:500]}",
+                status_code=exc.response.status_code,
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise LoxoError(
+                f"Loxo {method} {endpoint} request failed: {exc}", status_code=None
+            ) from exc
+        if not response.content:
+            return None
+        return response.json()
+
+    def get(self, endpoint: str, **kw: Any) -> Any:
+        return self.request("GET", endpoint, **kw)
+
+    def post(self, endpoint: str, **kw: Any) -> Any:
+        return self.request("POST", endpoint, **kw)
+
+    def put(self, endpoint: str, **kw: Any) -> Any:
+        return self.request("PUT", endpoint, **kw)
+
+    def delete(self, endpoint: str, **kw: Any) -> Any:
+        return self.request("DELETE", endpoint, **kw)
+
+
+def build_client(settings: LoxoSettings, *, verbose: bool = False) -> LoxoClient:
+    return LoxoClient(settings, verbose=verbose)

loxo_cli/commands/_app.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+from typer.core import TyperGroup
+
+from loxo_cli.errors import ConfigError, LoxoError
+
+
+class LoxoGroup(TyperGroup):
+    """Root command group that maps loxo's domain errors to documented exit codes.
+
+    Typer's invocation path does NOT honor a raised ``ClickException``'s
+    ``exit_code`` (it surfaces as a generic exit 1 with no message). Set this as
+    the root app's group class via the supported ``typer.Typer(cls=LoxoGroup)``
+    hook: its ``invoke`` wraps the entire command tree, so every command — nested
+    sub-app commands and root-level commands alike — gets its ``LoxoError`` /
+    ``ConfigError`` converted into ``typer.Exit`` with the mapped code, with a
+    clean message on stderr. Command files stay plain ``typer.Typer``.
+    """
+
+    def invoke(self, ctx) -> Any:  # ctx is typer's vendored-click Context
+        try:
+            return super().invoke(ctx)
+        except (LoxoError, ConfigError) as exc:
+            typer.echo(f"Error: {exc.format_message()}", err=True)
+            raise typer.Exit(code=exc.exit_code) from exc

loxo_cli/commands/_helpers.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any, TextIO
+
+import typer
+
+
+def load_data(raw: str | None, *, stdin: TextIO | None = None) -> dict:
+    if raw is None:
+        return {}
+    try:
+        if raw == "-":
+            source = stdin or sys.stdin
+            return json.load(source)
+        if raw.startswith("@"):
+            return json.loads(Path(raw[1:]).read_text())
+        return json.loads(raw)
+    except (json.JSONDecodeError, OSError) as exc:
+        raise typer.BadParameter(f"Invalid --data JSON: {exc}") from exc
+
+
+def parse_fields(fields: list[str]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for item in fields:
+        if "=" not in item:
+            raise typer.BadParameter(f"--field must be key=value, got {item!r}")
+        key, value = item.split("=", 1)
+        force_list = key.endswith("[]")
+        if force_list:
+            key = key[:-2]
+        if key in result:
+            existing = result[key]
+            result[key] = existing + [value] if isinstance(existing, list) else [existing, value]
+        elif force_list:
+            result[key] = [value]
+        else:
+            result[key] = value
+    return result
+
+
+def build_payload(resource_key: str, typed: dict, data: dict, fields: dict) -> dict:
+    merged: dict[str, Any] = dict(data)
+    merged.update({k: v for k, v in typed.items() if v is not None})
+    merged.update(fields)
+    return {resource_key: merged}

loxo_cli/commands/activities.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from loxo_cli.commands._helpers import build_payload, load_data, parse_fields
+from loxo_cli.pagination import paginate
+
+activities_app = typer.Typer(
+    help="Manage person events/activities. Unofficial — not affiliated with Loxo, Inc."
+)
+
+
+@activities_app.command("list")
+def list_activities(
+    ctx: typer.Context,
+    person_id: Optional[int] = typer.Option(None, "--person-id"),
+    job_id: Optional[int] = typer.Option(None, "--job-id"),
+    all_pages: bool = typer.Option(False, "--all"),
+    per_page: int = typer.Option(50, "--per-page"),
+) -> None:
+    state = ctx.obj
+    params: dict = {}
+    if person_id is not None:
+        params["person_id"] = person_id
+    if job_id is not None:
+        params["job_id"] = job_id
+    client = state.client()
+    if all_pages:
+        rows = list(
+            paginate(
+                client,
+                "person_events",
+                scheme="scroll_id",
+                items_key="person_events",
+                params=params,
+                per_page=per_page,
+            )
+        )
+    else:
+        params["per_page"] = per_page
+        data = client.get("person_events", params=params)
+        rows = data.get("person_events", []) if isinstance(data, dict) else data
+    state.emit(rows, columns=["id", "activity_type_id", "person_id", "notes"])
+
+
+@activities_app.command("add")
+def add_activity(
+    ctx: typer.Context,
+    activity_type_id: int = typer.Option(..., "--activity-type-id"),
+    person_id: int = typer.Option(..., "--person-id"),
+    job_id: Optional[int] = typer.Option(None, "--job-id"),
+    company_id: Optional[int] = typer.Option(None, "--company-id"),
+    notes: Optional[str] = typer.Option(None, "--notes"),
+    field: list[str] = typer.Option([], "--field"),
+    data: Optional[str] = typer.Option(None, "--data", "-d"),
+) -> None:
+    state = ctx.obj
+    raw = load_data(data)
+    inner = raw.get("person_event", raw)
+    typed = {
+        "activity_type_id": activity_type_id,
+        "person_id": person_id,
+        "job_id": job_id,
+        "company_id": company_id,
+        "notes": notes,
+    }
+    payload = build_payload("person_event", typed, inner, parse_fields(field))
+    result = state.client().post("person_events", json=payload)
+    state.emit(result)

loxo_cli/commands/api.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from loxo_cli.commands._helpers import load_data, parse_fields
+from loxo_cli.pagination import detect_scheme, extract_items, paginate
+
+
+def register(app: typer.Typer) -> None:
+    app.command(
+        "api",
+        help="Call any Loxo endpoint directly. " "Unofficial — not affiliated with Loxo, Inc.",
+    )(api_command)
+
+
+def api_command(
+    ctx: typer.Context,
+    method: str = typer.Argument(..., help="HTTP method: GET/POST/PUT/DELETE."),
+    path: str = typer.Argument(..., help="Endpoint path, e.g. people or jobs/123."),
+    param: list[str] = typer.Option(
+        [], "--param", "-p", help="Query param key=value (repeatable)."
+    ),
+    data: Optional[str] = typer.Option(
+        None, "--data", "-d", help="JSON body: inline, @file, or - for stdin."
+    ),
+    raw: bool = typer.Option(False, "--raw", help="No-op for the generic command (always raw)."),
+    all_pages: bool = typer.Option(False, "--all", help="Auto-paginate all pages."),
+    paginate_scheme: Optional[str] = typer.Option(
+        None, "--paginate", help="Force scheme: scroll_id|page|after_id."
+    ),
+) -> None:
+    state = ctx.obj
+    params = parse_fields(param)
+    body = load_data(data) or None
+    client = state.client()
+
+    if all_pages:
+        if method.upper() != "GET":
+            raise typer.BadParameter("--all only supports GET (pagination is GET-only).")
+        scheme = paginate_scheme
+        if scheme is None:
+            first = client.get(path, params=params)
+            scheme = detect_scheme(first)
+            # Collect first page items and build continuation params so we
+            # don't re-fetch the first page inside paginate().
+            first_items = extract_items(first, None)
+            cont_params = dict(params or {})
+            if scheme == "scroll_id" and isinstance(first, dict):
+                next_sid = first.get("scroll_id")
+                if next_sid:
+                    cont_params["scroll_id"] = next_sid
+                    items = first_items + list(
+                        paginate(client, path, scheme=scheme, params=cont_params)
+                    )
+                else:
+                    items = first_items
+            else:
+                # For page / after_id schemes, fall back to re-paginating from
+                # the start; the first-page data is small and the scheme is rare.
+                items = list(paginate(client, path, scheme=scheme, params=params))
+        else:
+            items = list(paginate(client, path, scheme=scheme, params=params))
+        state.emit(items)
+        return
+
+    result = client.request(method.upper(), path, params=params, json=body)
+    state.emit(result)

loxo_cli/commands/candidates.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from loxo_cli.commands._helpers import load_data, parse_fields
+from loxo_cli.models.candidate import Candidate
+from loxo_cli.pagination import paginate
+
+candidates_app = typer.Typer(
+    help="Manage job candidates. Unofficial — not affiliated with Loxo, Inc."
+)
+
+LIST_COLUMNS = ["id", "person_id", "job_id"]
+
+
+@candidates_app.command("list")
+def list_candidates(
+    ctx: typer.Context,
+    job: int = typer.Option(..., "--job", "-j"),
+    all_pages: bool = typer.Option(False, "--all"),
+    per_page: int = typer.Option(50, "--per-page"),
+) -> None:
+    state = ctx.obj
+    endpoint = f"jobs/{job}/candidates"
+    client = state.client()
+    if all_pages:
+        rows = [
+            Candidate.model_validate(i)
+            for i in paginate(
+                client, endpoint, scheme="scroll_id", items_key="candidates", per_page=per_page
+            )
+        ]
+    else:
+        data = client.get(endpoint, params={"per_page": per_page})
+        rows = [Candidate.model_validate(i) for i in data.get("candidates", [])]
+    state.emit(rows, columns=LIST_COLUMNS)
+
+
+@candidates_app.command("get")
+def get_candidate(
+    ctx: typer.Context,
+    candidate_id: int = typer.Argument(...),
+    job: int = typer.Option(..., "--job", "-j"),
+) -> None:
+    state = ctx.obj
+    data = state.client().get(f"jobs/{job}/candidates/{candidate_id}")
+    state.emit(Candidate.model_validate(data))
+
+
+@candidates_app.command(
+    "add",
+    help="Add a person to a job as a candidate. If Loxo rejects the body shape, "
+    "use `loxo api POST jobs/<id>/candidates --data @body.json`.",
+)
+def add_candidate(
+    ctx: typer.Context,
+    job: int = typer.Option(..., "--job", "-j"),
+    person: int = typer.Option(..., "--person"),
+    field: list[str] = typer.Option([], "--field"),
+    data: Optional[str] = typer.Option(None, "--data", "-d"),
+) -> None:
+    state = ctx.obj
+    body = load_data(data)
+    body.setdefault("person_id", person)
+    body.update(parse_fields(field))
+    result = state.client().post(f"jobs/{job}/candidates", json=body)
+    state.emit(Candidate.model_validate(result) if isinstance(result, dict) else result)
+
+
+@candidates_app.command("update")
+def update_candidate(
+    ctx: typer.Context,
+    candidate_id: int = typer.Argument(...),
+    job: int = typer.Option(..., "--job", "-j"),
+    highlights: Optional[str] = typer.Option(None, "--highlights"),
+    field: list[str] = typer.Option([], "--field"),
+    data: Optional[str] = typer.Option(None, "--data", "-d"),
+) -> None:
+    state = ctx.obj
+    body = load_data(data)
+    if highlights is not None:
+        body["highlights"] = highlights
+    body.update(parse_fields(field))
+    result = state.client().put(f"jobs/{job}/candidates/{candidate_id}", json=body)
+    state.emit(result)

loxo_cli/commands/companies.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from loxo_cli.commands._helpers import build_payload, load_data, parse_fields
+from loxo_cli.models.base import unwrap_envelope
+from loxo_cli.models.company import Company
+from loxo_cli.pagination import paginate
+
+companies_app = typer.Typer(help="Manage companies. Unofficial — not affiliated with Loxo, Inc.")
+
+LIST_COLUMNS = ["id", "name", "url"]
+
+
+def _list(state, query, all_pages, per_page):
+    params = {"query": query} if query else {}
+    client = state.client()
+    if all_pages:
+        rows = [
+            Company.model_validate(i)
+            for i in paginate(
+                client,
+                "companies",
+                scheme="scroll_id",
+                items_key="companies",
+                params=params,
+                per_page=per_page,
+            )
+        ]
+    else:
+        params["per_page"] = per_page
+        data = client.get("companies", params=params)
+        rows = [Company.model_validate(i) for i in data.get("companies", [])]
+    state.emit(rows, columns=LIST_COLUMNS)
+
+
+@companies_app.command("list")
+def list_companies(
+    ctx: typer.Context,
+    query: Optional[str] = typer.Option(None, "--query", "-q"),
+    all_pages: bool = typer.Option(False, "--all"),
+    per_page: int = typer.Option(50, "--per-page"),
+) -> None:
+    _list(ctx.obj, query, all_pages, per_page)
+
+
+@companies_app.command(
+    "search",
+    help="Search companies by query. NOTE: the company 'url' field is not a "
+    "searchable Lucene field; pass a bare domain as a full-text query.",
+)
+def search_companies(
+    ctx: typer.Context,
+    query: str = typer.Option(..., "--query", "-q"),
+    all_pages: bool = typer.Option(False, "--all"),
+    per_page: int = typer.Option(50, "--per-page"),
+) -> None:
+    _list(ctx.obj, query, all_pages, per_page)
+
+
+@companies_app.command("get")
+def get_company(ctx: typer.Context, company_id: int = typer.Argument(...)) -> None:
+    state = ctx.obj
+    data = state.client().get(f"companies/{company_id}")
+    state.emit(Company.model_validate(unwrap_envelope(data, "company")))
+
+
+@companies_app.command("create")
+def create_company(
+    ctx: typer.Context,
+    name: Optional[str] = typer.Option(None, "--name"),
+    url: Optional[str] = typer.Option(None, "--url"),
+    field: list[str] = typer.Option([], "--field"),
+    data: Optional[str] = typer.Option(None, "--data", "-d"),
+) -> None:
+    state = ctx.obj
+    raw = load_data(data)
+    inner = raw.get("company", raw)
+    payload = build_payload("company", {"name": name, "url": url}, inner, parse_fields(field))
+    result = state.client().post("companies", json=payload)
+    state.emit(Company.model_validate(unwrap_envelope(result, "company")))
+
+
+@companies_app.command("update")
+def update_company(
+    ctx: typer.Context,
+    company_id: int = typer.Argument(...),
+    name: Optional[str] = typer.Option(None, "--name"),
+    url: Optional[str] = typer.Option(None, "--url"),
+    field: list[str] = typer.Option([], "--field"),
+    data: Optional[str] = typer.Option(None, "--data", "-d"),
+) -> None:
+    state = ctx.obj
+    raw = load_data(data)
+    inner = raw.get("company", raw)
+    payload = build_payload("company", {"name": name, "url": url}, inner, parse_fields(field))
+    result = state.client().put(f"companies/{company_id}", json=payload)
+    state.emit(Company.model_validate(unwrap_envelope(result, "company")))

loxo_cli/commands/configure.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from loxo_cli.config import DEFAULT_BASE_URL, config_file_path, list_profiles, write_profile
+
+configure_app = typer.Typer(
+    help="Set up credential profiles. Unofficial — not affiliated with Loxo, Inc.",
+    invoke_without_command=True,
+)
+
+
+@configure_app.callback(invoke_without_command=True)
+def configure(
+    ctx: typer.Context,
+    name: Optional[str] = typer.Option(None, "--name"),
+    slug: Optional[str] = typer.Option(None, "--slug"),
+    base_url: Optional[str] = typer.Option(None, "--base-url"),
+    api_key: Optional[str] = typer.Option(None, "--api-key"),
+    config_path: Optional[Path] = typer.Option(None, "--config-path"),
+) -> None:
+    if ctx.invoked_subcommand is not None:
+        return
+    name = name or typer.prompt("Profile name", default="default")
+    slug = slug or typer.prompt("Agency slug")
+    base_url = base_url or DEFAULT_BASE_URL
+    api_key = api_key or typer.prompt("API key", hide_input=True)
+    write_profile(
+        name,
+        api_key=api_key,
+        slug=slug,
+        base_url=base_url,
+        make_default=False,
+        config_path=config_path,
+    )
+    target = config_path or config_file_path()
+    typer.echo(f"Saved profile '{name}' to {target}")
+
+
+@configure_app.command("list")
+def list_cmd(
+    config_path: Optional[Path] = typer.Option(None, "--config-path"),
+) -> None:
+    profiles = list_profiles(config_path=config_path)
+    if not profiles:
+        typer.echo("No profiles configured. Run `loxo configure`.")
+        return
+    for pname, info in profiles.items():
+        default = " (default)" if info["default"] else ""
+        key = "set" if info["has_key"] else "missing"
+        typer.echo(
+            f"{pname}{default}: slug={info['slug']} " f"base_url={info['base_url']} api_key={key}"
+        )