akt-cli 0.1.0__py3-none-any.whl

akt/__init__.py

@@ -0,0 +1,6 @@
+"""akt — a CLI toolbox for driving an Akaunting accounting instance."""
+
+from .cli import main
+
+__all__ = ["main"]
+__version__ = "0.1.0"

akt/cli.py

@@ -0,0 +1,211 @@
+"""akt — command-line toolbox for an Akaunting accounting instance."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from .client import ApiError, Client
+from .config import ConfigError, load_config
+from .commands import (
+    cmd_create,
+    cmd_delete,
+    cmd_get,
+    cmd_list,
+    cmd_toggle,
+    cmd_update,
+)
+from .output import emit
+from .registry import RESOURCES, BY_NOUN
+from .resources import Resource, load_data_arg
+
+
+def _add_field_args(p: argparse.ArgumentParser, res: Resource, *, for_update: bool) -> None:
+    for fld in res.fields:
+        flag = f"--{fld.name}"
+        if fld.is_flag:
+            grp = p.add_mutually_exclusive_group()
+            grp.add_argument(f"--{fld.name}", dest=fld.dest, action="store_true",
+                             default=None, help=fld.help)
+            negname = "disabled" if fld.name == "enabled" else f"no-{fld.name}"
+            grp.add_argument(f"--{negname}", dest=fld.dest, action="store_false",
+                             default=None, help=argparse.SUPPRESS)
+        else:
+            req = fld.required and not for_update and res.build_create is None
+            p.add_argument(flag, dest=fld.dest, metavar=fld.dest.upper(),
+                           required=req, choices=fld.choices, help=fld.help)
+    if res.endpoint == "documents":
+        p.add_argument("--item", action="append", metavar="K=V,...",
+                       help="line item, e.g. 'name=Widget,price=10,quantity=2,tax_id=1' (repeatable)")
+    p.add_argument("--set", dest="set_", action="append", metavar="KEY=VALUE",
+                   help="set an arbitrary body field (repeatable; value JSON-coerced)")
+    p.add_argument("--data", metavar="JSON|@FILE",
+                   help="merge raw JSON body (inline or @file) — wins over other flags")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    # --json lives on a parent parser shared by every subcommand so it works
+    # both before the subcommand (akt --json customer list) and after it
+    # (akt customer list --json). default=SUPPRESS stops subparser parsing from
+    # clobbering a value supplied at the top level.
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--json", dest="json", action="store_true", default=argparse.SUPPRESS,
+                        help="Force raw JSON output")
+
+    parser = argparse.ArgumentParser(
+        prog="akt",
+        parents=[common],
+        description="Drive an Akaunting accounting instance from the command line.",
+    )
+    # Connection flags are top-level only (given before the subcommand) so their
+    # option strings never collide with a resource's own --email / --currency-code
+    # etc. Distinct conn_* dests also keep them out of the field namespace.
+    parser.add_argument("--base-url", dest="conn_base_url",
+                        help="API base URL (or AKT_BASE_URL / APP_URL)")
+    parser.add_argument("--email", dest="conn_email", help="Admin email (or AKT_EMAIL)")
+    parser.add_argument("--password", dest="conn_password", help="Admin password (or AKT_PASSWORD)")
+    parser.add_argument("--company", dest="conn_company", help="Company id (default 1, or AKT_COMPANY)")
+    parser.add_argument("--throttle", dest="conn_throttle", type=float, default=None,
+                        metavar="SECONDS",
+                        help="Min seconds between API calls (or AKT_THROTTLE). "
+                             "Use a value like 1.0 to avoid tripping host bot-protection.")
+
+    sub = parser.add_subparsers(dest="resource", metavar="<resource>")
+
+    for res in RESOURCES:
+        rp = sub.add_parser(res.noun, help=res.help)
+        verbs = rp.add_subparsers(dest="verb", metavar="<verb>")
+
+        lp = verbs.add_parser("list", parents=[common], help=f"List {res.noun}s")
+        lp.add_argument("--search", default="", help="search-string filter (e.g. 'name:Acme')")
+        lp.add_argument("--all", action="store_true", help="fetch all pages")
+        lp.add_argument("--limit", type=int, help="records per page")
+        lp.set_defaults(_handler=lambda res, c, ns: cmd_list(res, c, ns))
+
+        gp = verbs.add_parser("get", parents=[common], help=f"Show one {res.noun} by id")
+        gp.add_argument("id")
+        gp.set_defaults(_handler=lambda res, c, ns: cmd_get(res, c, ns))
+
+        cp = verbs.add_parser("create", parents=[common], help=f"Create a {res.noun}")
+        _add_field_args(cp, res, for_update=False)
+        cp.set_defaults(_handler=lambda res, c, ns: cmd_create(res, c, ns))
+
+        up = verbs.add_parser("update", parents=[common], help=f"Update a {res.noun}")
+        up.add_argument("id")
+        _add_field_args(up, res, for_update=True)
+        up.set_defaults(_handler=lambda res, c, ns: cmd_update(res, c, ns))
+
+        dp = verbs.add_parser("delete", parents=[common], help=f"Delete a {res.noun}")
+        dp.add_argument("id")
+        dp.set_defaults(_handler=lambda res, c, ns: cmd_delete(res, c, ns))
+
+        if res.supports_toggle:
+            ep = verbs.add_parser("enable", parents=[common], help=f"Enable a {res.noun}")
+            ep.add_argument("id")
+            ep.set_defaults(_handler=lambda res, c, ns: cmd_toggle(res, c, ns, True))
+            xp = verbs.add_parser("disable", parents=[common], help=f"Disable a {res.noun}")
+            xp.add_argument("id")
+            xp.set_defaults(_handler=lambda res, c, ns: cmd_toggle(res, c, ns, False))
+
+    # ---- non-resource utility commands ----
+    pp = sub.add_parser("ping", parents=[common], help="Health check (unauthenticated)")
+    pp.set_defaults(_special="ping")
+
+    cp = sub.add_parser("company", parents=[common], help="List companies / show current")
+    cp.set_defaults(_special="company")
+
+    sp = sub.add_parser("settings", parents=[common], help="List company settings")
+    sp.add_argument("--search", default="", help="e.g. 'key:default.account'")
+    sp.set_defaults(_special="settings")
+
+    rp = sub.add_parser("raw", parents=[common], help="Call an arbitrary API endpoint")
+    rp.add_argument("method", choices=["GET", "POST", "PUT", "PATCH", "DELETE",
+                                       "get", "post", "put", "patch", "delete"])
+    rp.add_argument("path", help="endpoint path, e.g. 'items' or 'documents/5'")
+    rp.add_argument("--data", metavar="JSON|@FILE", help="request body (inline JSON or @file)")
+    rp.add_argument("--query", action="append", metavar="K=V", help="query param (repeatable)")
+    rp.add_argument("--type-scope", help="search=type:X scope for contacts/documents")
+    rp.set_defaults(_special="raw")
+
+    return parser
+
+
+def _run_special(name: str, client: Client, ns: Any) -> int:
+    if name == "ping":
+        emit(client.get("ping"), as_json=True)
+        return 0
+    if name == "company":
+        rows = client.list("companies")
+        cols = ["id", "name", "email", "currency", "enabled"]
+        emit(rows, as_json=ns.json, columns=None if ns.json else cols,
+             headers=["ID", "Name", "Email", "Currency", "Enabled"])
+        return 0
+    if name == "settings":
+        rows = client.list("settings", search=ns.search or None, all_pages=True)
+        cols = ["id", "key", "value"]
+        emit(rows, as_json=ns.json, columns=None if ns.json else cols,
+             headers=["ID", "Key", "Value"])
+        return 0
+    if name == "raw":
+        params = dict(kv.split("=", 1) for kv in (ns.query or []))
+        body = load_data_arg(ns.data) if ns.data else None
+        result = client.request(ns.method.upper(), ns.path, params=params or None,
+                                json_body=body, type_scope=ns.type_scope)
+        emit(result, as_json=True)
+        return 0
+    raise ValueError(name)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    ns = parser.parse_args(argv)
+
+    if not getattr(ns, "resource", None):
+        parser.print_help()
+        return 1
+
+    # Flags on the shared parent use default=SUPPRESS; backfill them here.
+    ns.json = getattr(ns, "json", False)
+
+    try:
+        config = load_config(
+            base_url=getattr(ns, "conn_base_url", None),
+            email=getattr(ns, "conn_email", None),
+            password=getattr(ns, "conn_password", None),
+            company=getattr(ns, "conn_company", None),
+        )
+    except ConfigError as e:
+        print(f"config error: {e}", file=sys.stderr)
+        return 2
+
+    import os
+    throttle = getattr(ns, "conn_throttle", None)
+    if throttle is None:
+        throttle = float(os.environ.get("AKT_THROTTLE", "0") or 0)
+    client = Client(config, throttle=throttle)
+
+    try:
+        special = getattr(ns, "_special", None)
+        if special:
+            return _run_special(special, client, ns)
+
+        res = BY_NOUN[ns.resource]
+        handler = getattr(ns, "_handler", None)
+        if handler is None:
+            # resource given without a verb
+            sub = next(a for a in parser._subparsers._actions  # type: ignore[attr-defined]
+                       if a.dest == "resource")
+            sub.choices[ns.resource].print_help()  # type: ignore[union-attr]
+            return 1
+        return handler(res, client, ns)
+    except ApiError as e:
+        print(str(e), file=sys.stderr)
+        return 1
+    except (ValueError, OSError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

akt/client.py

@@ -0,0 +1,240 @@
+"""Thin HTTP client for the Akaunting REST API.
+
+Akaunting specifics baked in here:
+  * HTTP Basic auth (admin email + password).
+  * Every company-scoped request carries ``company_id`` as a query param.
+  * The ``contacts`` and ``documents`` controllers derive their ACL permission
+    from a ``search=type:<x>`` query param, so for those endpoints the caller
+    must pass ``type_scope`` on *every* verb (GET/POST/PUT/DELETE) or the API
+    returns 403 "necessary access rights".
+  * Responses are JSON-API-ish: a single object under ``data`` for show/create,
+    a list under ``data`` plus ``meta`` pagination for index.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Iterator
+
+import requests
+
+from .config import Config
+
+# Imunify360 / generic WAF + throttle responses we transparently retry.
+_RETRY_STATUS = {429, 503}
+_WAF_MARKERS = ("imunify360", "bot-protection", "bot protection", "access denied by")
+_RETRY_BACKOFF = [2.0, 5.0, 10.0, 20.0]
+
+
+class ApiError(Exception):
+    """An error returned by the Akaunting API (non-2xx)."""
+
+    def __init__(self, status: int, message: str, errors: dict | None = None, body: Any = None):
+        self.status = status
+        self.message = message
+        self.errors = errors or {}
+        self.body = body
+        super().__init__(self._format())
+
+    def _format(self) -> str:
+        out = f"HTTP {self.status}: {self.message}"
+        for field, msgs in self.errors.items():
+            if isinstance(msgs, list):
+                for m in msgs:
+                    out += f"\n  - {field}: {m}"
+            else:
+                out += f"\n  - {field}: {msgs}"
+        return out
+
+
+def _is_transient(resp: requests.Response) -> bool:
+    """True for throttle / WAF responses worth retrying."""
+    if resp.status_code in _RETRY_STATUS:
+        return True
+    body = (resp.text or "").lower()
+    return any(m in body for m in _WAF_MARKERS)
+
+
+class Client:
+    def __init__(self, config: Config, *, timeout: float = 30.0, max_retries: int = 4,
+                 throttle: float = 0.0):
+        self.config = config
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.throttle = throttle  # min seconds between requests (anti-WAF)
+        self._last_request = 0.0
+        self._settings_cache: dict[str, Any] = {}
+        self._settings_loaded = False
+        self._session = requests.Session()
+        self._session.auth = (config.email, config.password)
+        self._session.headers.update(
+            {
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+                "User-Agent": "akt/0.1 (+akaunting-cli)",
+            }
+        )
+
+    # ---- low level -----------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict | None = None,
+        json_body: Any = None,
+        type_scope: str | None = None,
+    ) -> Any:
+        url = f"{self.config.api_root}/{path.lstrip('/')}"
+        query: dict[str, Any] = {"company_id": self.config.company_id}
+        if type_scope:
+            # merge into a search-string; preserve any caller-provided search
+            existing = (params or {}).get("search", "")
+            scope = f"type:{type_scope}"
+            query["search"] = f"{scope} {existing}".strip() if existing else scope
+        if params:
+            for k, v in params.items():
+                if v is None:
+                    continue
+                if k == "search" and type_scope:
+                    continue  # already merged
+                query[k] = v
+
+        data = None
+        if json_body is not None:
+            data = json.dumps(json_body)
+
+        attempt = 0
+        while True:
+            if self.throttle > 0:
+                wait = self.throttle - (time.monotonic() - self._last_request)
+                if wait > 0:
+                    time.sleep(wait)
+            self._last_request = time.monotonic()
+            resp = self._session.request(
+                method.upper(),
+                url,
+                params=query,
+                data=data,
+                timeout=self.timeout,
+            )
+            if attempt < self.max_retries and _is_transient(resp):
+                delay = _RETRY_BACKOFF[min(attempt, len(_RETRY_BACKOFF) - 1)]
+                time.sleep(delay)
+                attempt += 1
+                continue
+            return self._handle(resp)
+
+    @staticmethod
+    def _waf_blocked(resp: requests.Response) -> bool:
+        body = (resp.text or "").lower()
+        return any(m in body for m in _WAF_MARKERS)
+
+    def _handle(self, resp: requests.Response) -> Any:
+        if self._waf_blocked(resp):
+            raise ApiError(
+                resp.status_code,
+                "Blocked by Imunify360 bot-protection after retries. "
+                "Whitelist this machine's public IP in the host's Imunify360 / "
+                "cPanel firewall, or retry later.",
+            )
+        if resp.status_code == 204 or not resp.content:
+            if resp.ok:
+                return None
+            raise ApiError(resp.status_code, resp.reason or "Request failed")
+        try:
+            payload = resp.json()
+        except ValueError:
+            if resp.ok:
+                return resp.text
+            raise ApiError(resp.status_code, resp.text[:500] or resp.reason or "Request failed")
+
+        if not resp.ok:
+            message = "Request failed"
+            errors = None
+            if isinstance(payload, dict):
+                message = payload.get("message") or payload.get("error") or message
+                errors = payload.get("errors")
+            raise ApiError(resp.status_code, message, errors, payload)
+        return payload
+
+    # ---- convenience verbs --------------------------------------------
+
+    def get(self, path: str, **kw) -> Any:
+        return self.request("GET", path, **kw)
+
+    def post(self, path: str, json_body: Any, **kw) -> Any:
+        return self.request("POST", path, json_body=json_body, **kw)
+
+    def put(self, path: str, json_body: Any, **kw) -> Any:
+        return self.request("PUT", path, json_body=json_body, **kw)
+
+    def delete(self, path: str, **kw) -> Any:
+        return self.request("DELETE", path, **kw)
+
+    # ---- higher level helpers -----------------------------------------
+
+    def list(
+        self,
+        path: str,
+        *,
+        type_scope: str | None = None,
+        search: str | None = None,
+        params: dict | None = None,
+        all_pages: bool = False,
+        limit: int | None = None,
+    ) -> list[dict]:
+        """Return the ``data`` list. Optionally follow pagination."""
+        p: dict[str, Any] = dict(params or {})
+        if search:
+            p["search"] = search
+        if limit:
+            p["limit"] = limit
+        page = 1
+        out: list[dict] = []
+        while True:
+            p["page"] = page
+            payload = self.get(path, params=p, type_scope=type_scope)
+            data = payload.get("data", []) if isinstance(payload, dict) else []
+            out.extend(data)
+            if not all_pages:
+                break
+            meta = payload.get("meta", {}) if isinstance(payload, dict) else {}
+            last = meta.get("last_page", page)
+            if page >= last:
+                break
+            page += 1
+        return out
+
+    def iter_pages(self, path: str, *, type_scope: str | None = None, search: str | None = None,
+                   params: dict | None = None) -> Iterator[dict]:
+        p: dict[str, Any] = dict(params or {})
+        if search:
+            p["search"] = search
+        page = 1
+        while True:
+            p["page"] = page
+            payload = self.get(path, params=p, type_scope=type_scope)
+            for row in (payload.get("data", []) if isinstance(payload, dict) else []):
+                yield row
+            meta = payload.get("meta", {}) if isinstance(payload, dict) else {}
+            last = meta.get("last_page", page)
+            if page >= last:
+                break
+            page += 1
+
+    def show(self, path: str, ident: str | int, *, type_scope: str | None = None) -> dict:
+        payload = self.get(f"{path}/{ident}", type_scope=type_scope)
+        if isinstance(payload, dict) and "data" in payload:
+            return payload["data"]
+        return payload
+
+    def setting(self, key: str, default: Any = None) -> Any:
+        """Read a single company setting value by key (cached after first call)."""
+        if not self._settings_loaded:
+            rows = self.list("settings", all_pages=True)
+            self._settings_cache = {str(r.get("key")): r.get("value") for r in rows}
+            self._settings_loaded = True
+        return self._settings_cache.get(key, default)

akt/commands.py

@@ -0,0 +1,88 @@
+"""Generic command handlers shared by every resource."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .client import Client
+from .output import emit
+from .resources import Resource, body_from_fields
+
+
+def cmd_list(res: Resource, client: Client, ns: Any) -> int:
+    search = ns.search
+    if res.search_default:
+        search = f"{res.search_default} {search}".strip() if search else res.search_default
+    rows = client.list(
+        res.endpoint,
+        type_scope=res.type_scope,
+        search=search or None,
+        all_pages=ns.all,
+        limit=ns.limit,
+    )
+    cols = [c[1] for c in res.columns]
+    heads = [c[0] for c in res.columns]
+    emit(rows, as_json=ns.json, columns=cols if not ns.json else None, headers=heads)
+    return 0
+
+
+def cmd_get(res: Resource, client: Client, ns: Any) -> int:
+    row = client.show(res.endpoint, ns.id, type_scope=res.type_scope)
+    emit(row, as_json=True)
+    return 0
+
+
+def cmd_create(res: Resource, client: Client, ns: Any) -> int:
+    if res.build_create:
+        body = res.build_create(res, client, ns)
+    else:
+        body = body_from_fields(res, ns, for_update=False)
+        _require(res, body)
+    # A builder may override the target route via reserved keys (e.g. paying a
+    # document goes to documents/{id}/transactions).
+    endpoint = body.pop("__endpoint__", res.endpoint)
+    type_scope = body.pop("__type_scope__", res.type_scope)
+    payload = client.post(endpoint, body, type_scope=type_scope)
+    data = payload.get("data", payload) if isinstance(payload, dict) else payload
+    emit(data, as_json=True)
+    return 0
+
+
+def cmd_update(res: Resource, client: Client, ns: Any) -> int:
+    if res.build_update:
+        current = client.show(res.endpoint, ns.id, type_scope=res.type_scope)
+        body = res.build_update(res, client, ns, current)
+    else:
+        # PUT is a full replace in Akaunting, so merge changes onto the current
+        # record to satisfy required-field validation.
+        current = client.show(res.endpoint, ns.id, type_scope=res.type_scope)
+        body = body_from_fields(res, ns, for_update=True, current=current)
+    payload = client.put(f"{res.endpoint}/{ns.id}", body, type_scope=res.type_scope)
+    data = payload.get("data", payload) if isinstance(payload, dict) else payload
+    emit(data, as_json=True)
+    return 0
+
+
+def cmd_delete(res: Resource, client: Client, ns: Any) -> int:
+    if res.delete_resolver:
+        path, type_scope = res.delete_resolver(res, client, str(ns.id))
+    else:
+        path, type_scope = f"{res.endpoint}/{ns.id}", res.type_scope
+    client.delete(path, type_scope=type_scope)
+    print(f"deleted {res.noun} {ns.id}")
+    return 0
+
+
+def cmd_toggle(res: Resource, client: Client, ns: Any, enable: bool) -> int:
+    # Akaunting exposes GET enable/disable endpoints
+    action = "enable" if enable else "disable"
+    payload = client.get(f"{res.endpoint}/{ns.id}/{action}", type_scope=res.type_scope)
+    data = payload.get("data", payload) if isinstance(payload, dict) else payload
+    emit(data, as_json=True)
+    return 0
+
+
+def _require(res: Resource, body: dict) -> None:
+    missing = [fld.dest for fld in res.fields if fld.required and fld.dest not in body]
+    if missing:
+        raise ValueError(f"missing required field(s): {', '.join(missing)}")

akt/config.py

@@ -0,0 +1,121 @@
+"""Configuration loading for akt.
+
+Resolution order (highest priority first):
+  1. Explicit CLI flags (--base-url, --email, --password, --company)
+  2. Environment variables (AKT_BASE_URL, AKT_EMAIL, AKT_PASSWORD, AKT_COMPANY)
+  3. A dotenv file: $AKT_ENV_FILE, or ./.env, or ~/.config/akt/akt.env
+     Recognised keys: APP_URL / AKT_BASE_URL, AKAUNTING_ADMIN_EMAIL / AKT_EMAIL,
+     AKAUNTING_ADMIN_PASSWORD / AKT_PASSWORD, AKT_COMPANY.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def _parse_dotenv(path: Path) -> dict[str, str]:
+    data: dict[str, str] = {}
+    try:
+        text = path.read_text()
+    except OSError:
+        return data
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, val = line.partition("=")
+        key = key.strip()
+        val = val.strip().strip('"').strip("'")
+        if key:
+            data[key] = val
+    return data
+
+
+def _candidate_env_files() -> list[Path]:
+    files: list[Path] = []
+    if os.environ.get("AKT_ENV_FILE"):
+        files.append(Path(os.environ["AKT_ENV_FILE"]).expanduser())
+    files.append(Path.cwd() / ".env")
+    files.append(Path.home() / ".config" / "akt" / "akt.env")
+    return files
+
+
+class ConfigError(Exception):
+    pass
+
+
+@dataclass
+class Config:
+    base_url: str
+    email: str
+    password: str
+    company_id: int
+
+    @property
+    def api_root(self) -> str:
+        base = self.base_url.rstrip("/")
+        if base.endswith("/api"):
+            return base
+        return base + "/api"
+
+
+def load_config(
+    *,
+    base_url: str | None = None,
+    email: str | None = None,
+    password: str | None = None,
+    company: int | str | None = None,
+) -> Config:
+    """Merge CLI args, environment, and dotenv files into a Config."""
+    filevals: dict[str, str] = {}
+    for f in _candidate_env_files():
+        for k, v in _parse_dotenv(f).items():
+            filevals.setdefault(k, v)  # earlier files win
+
+    def pick(cli, *keys, default=None):
+        if cli is not None and cli != "":
+            return cli
+        for k in keys:
+            if os.environ.get(k):
+                return os.environ[k]
+        for k in keys:
+            if filevals.get(k):
+                return filevals[k]
+        return default
+
+    resolved_base = pick(base_url, "AKT_BASE_URL", "APP_URL")
+    resolved_email = pick(email, "AKT_EMAIL", "AKAUNTING_ADMIN_EMAIL")
+    resolved_password = pick(password, "AKT_PASSWORD", "AKAUNTING_ADMIN_PASSWORD")
+    resolved_company = pick(company, "AKT_COMPANY", default="1")
+
+    missing = [
+        name
+        for name, val in [
+            ("base url", resolved_base),
+            ("email", resolved_email),
+            ("password", resolved_password),
+        ]
+        if not val
+    ]
+    if missing:
+        raise ConfigError(
+            "Missing required configuration: "
+            + ", ".join(missing)
+            + ".\nSet them via flags (--base-url/--email/--password), env vars "
+            "(AKT_BASE_URL/AKT_EMAIL/AKT_PASSWORD), or a .env file."
+        )
+
+    try:
+        company_id = int(resolved_company)
+    except (TypeError, ValueError):
+        raise ConfigError(f"Invalid company id: {resolved_company!r}")
+
+    assert resolved_base and resolved_email and resolved_password  # guarded above
+    return Config(
+        base_url=resolved_base,
+        email=resolved_email,
+        password=resolved_password,
+        company_id=company_id,
+    )