moneybird-cli 0.1.0__py3-none-any.whl

moneybird_cli/__init__.py

@@ -0,0 +1 @@
+"""Moneybird CLI - Command-line interface for the Moneybird API."""

moneybird_cli/client.py

@@ -0,0 +1,176 @@
+"""Moneybird API client with pagination, rate limiting, and error handling."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+import click
+import requests
+
+logger = logging.getLogger(__name__)
+
+API_BASE = "https://moneybird.com/api/v2"
+
+
+class MoneybirdApiError(click.ClickException):
+    """API error with HTTP status code context."""
+
+    def __init__(self, status_code: int, message: str) -> None:
+        self.status_code = status_code
+        super().__init__(f"API error {status_code}: {message}")
+
+
+class MoneybirdClient:
+    """HTTP client for the Moneybird API."""
+
+    def __init__(
+        self,
+        token: str,
+        administration_id: str,
+        dry_run: bool = False,
+        verbose: bool = False,
+        timezone: str | None = None,
+    ) -> None:
+        self.token = token
+        self.administration_id = administration_id
+        self.dry_run = dry_run
+        self.verbose = verbose
+        self.base_url = f"{API_BASE}/{administration_id}"
+        self.session = requests.Session()
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        if timezone:
+            headers["Time-Zone"] = timezone
+        self.session.headers.update(headers)
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}/{path}.json"
+
+    def _handle_response(self, response: requests.Response) -> tuple[Any, requests.Response]:
+        if response.status_code == 429:
+            retry_after = int(response.headers.get("Retry-After", "60"))
+            logger.warning("Rate limited. Retrying after %d seconds.", retry_after)
+            time.sleep(retry_after)
+            return self._handle_response(
+                self.session.send(response.request)  # type: ignore[arg-type]
+            )
+
+        if response.status_code == 204:
+            return None, response
+
+        if response.status_code >= 400:
+            try:
+                body = response.json()
+                message = body.get("error", body.get("message", response.text))
+            except (ValueError, KeyError):
+                message = response.text
+            raise MoneybirdApiError(response.status_code, message)
+
+        if not response.content:
+            return None, response
+        return response.json(), response
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict | None = None,
+        json: dict | None = None,
+    ) -> Any:
+        url = self._url(path)
+        if self.verbose:
+            click.echo(f"{method.upper()} {url}", err=True)
+            if json:
+                click.echo(f"  Body: {json}", err=True)
+
+        if self.dry_run and method.upper() != "GET":
+            click.echo(f"[dry-run] {method.upper()} {url}", err=True)
+            return None
+
+        response = self.session.request(method, url, params=params, json=json)
+        data, _ = self._handle_response(response)
+        return data
+
+    def _request_with_headers(
+        self,
+        method: str,
+        path: str,
+        params: dict | None = None,
+    ) -> tuple[Any, requests.Response]:
+        """Like _request, but also returns the response for header inspection."""
+        url = self._url(path)
+        if self.verbose:
+            click.echo(f"{method.upper()} {url}", err=True)
+
+        response = self.session.request(method, url, params=params)
+        return self._handle_response(response)
+
+    @staticmethod
+    def _respect_rate_limit(response: requests.Response, verbose: bool = False) -> None:
+        """Sleep if rate limit is nearly exhausted."""
+        remaining = response.headers.get("RateLimit-Remaining")
+        if remaining is not None and int(remaining) <= 1:
+            reset = int(response.headers.get("RateLimit-Reset", "60"))
+            if verbose:
+                click.echo(f"Rate limit nearly exhausted, waiting {reset}s.", err=True)
+            time.sleep(reset)
+
+    def get(self, path: str, params: dict | None = None) -> Any:
+        return self._request("GET", path, params=params)
+
+    @staticmethod
+    def list_administrations(token: str) -> list[dict]:
+        """List all administrations accessible with the given token."""
+        url = f"{API_BASE}/administrations.json"
+        response = requests.get(
+            url,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Accept": "application/json",
+            },
+        )
+        if response.status_code >= 400:
+            try:
+                body = response.json()
+                message = body.get("error", body.get("message", response.text))
+            except (ValueError, KeyError):
+                message = response.text
+            raise MoneybirdApiError(response.status_code, message)
+        return response.json()
+
+    def get_all(
+        self, path: str, params: dict | None = None, per_page: int = 100
+    ) -> list[dict]:
+        """GET with automatic pagination. Returns all results.
+
+        Respects rate limit headers: pauses when RateLimit-Remaining is low.
+        """
+        params = dict(params or {})
+        params["per_page"] = per_page
+        page = 1
+        results: list[dict] = []
+        while True:
+            params["page"] = page
+            data, response = self._request_with_headers("GET", path, params=params)
+            if not data:
+                break
+            results.extend(data)
+            if len(data) < per_page:
+                break
+            self._respect_rate_limit(response, verbose=self.verbose)
+            page += 1
+        return results
+
+    def post(self, path: str, json: dict | None = None) -> Any:
+        return self._request("POST", path, json=json)
+
+    def patch(self, path: str, json: dict | None = None) -> Any:
+        return self._request("PATCH", path, json=json)
+
+    def delete(self, path: str) -> Any:
+        return self._request("DELETE", path)

moneybird_cli/commands/assets.py

@@ -0,0 +1,87 @@
+"""Assets commands."""
+
+from __future__ import annotations
+
+import click
+
+from moneybird_cli.main import pass_context, Context
+from moneybird_cli.output import echo_output
+
+LIST_COLUMNS = ["id", "name", "purchase_date", "purchase_value", "current_value"]
+
+
+@click.group()
+def assets() -> None:
+    """Manage assets (company cars, laptops, furniture, etc.)."""
+
+
+@assets.command("list")
+@click.option("--all", "fetch_all", is_flag=True, help="Fetch all pages (respects rate limits).")
+@click.option("--include-inactive", is_flag=True, help="Include inactive assets.")
+@click.option("--ledger-account-id", help="Filter by ledger account ID.")
+@click.option("--page", type=int, default=None, help="Page number (default: 1).")
+@click.option("--per-page", type=int, default=None, help="Results per page (max 100).")
+@pass_context
+def list_assets(ctx: Context, fetch_all: bool, include_inactive: bool, ledger_account_id: str | None, page: int | None, per_page: int | None) -> None:
+    """List assets. Returns the first page by default; use --all to fetch everything."""
+    client = ctx.get_client()
+    params: dict = {}
+    if include_inactive:
+        params["active"] = "false"
+    if ledger_account_id:
+        params["ledger_account_id"] = ledger_account_id
+    if fetch_all:
+        data = client.get_all("assets", params=params, per_page=per_page or 100)
+    else:
+        params["page"] = page or 1
+        if per_page:
+            params["per_page"] = per_page
+        data = client.get("assets", params=params)
+    echo_output(data, fmt=ctx.output_format, columns=LIST_COLUMNS)
+
+
+@assets.command("get")
+@click.argument("id")
+@pass_context
+def get_asset(ctx: Context, id: str) -> None:
+    """Get a single asset by ID."""
+    client = ctx.get_client()
+    data = client.get(f"assets/{id}")
+    echo_output(data, fmt=ctx.output_format)
+
+
+@assets.command("create")
+@click.option("--name", required=True, help="Asset name.")
+@click.option("--purchase-date", help="Purchase date (YYYY-MM-DD).")
+@click.option("--purchase-value", help="Purchase value.")
+@pass_context
+def create_asset(ctx: Context, **kwargs: str | None) -> None:
+    """Create a new asset."""
+    client = ctx.get_client()
+    asset = {k: v for k, v in kwargs.items() if v is not None}
+    data = client.post("assets", json={"asset": asset})
+    echo_output(data, fmt=ctx.output_format)
+
+
+@assets.command("update")
+@click.argument("id")
+@click.option("--name", help="Asset name.")
+@pass_context
+def update_asset(ctx: Context, id: str, **kwargs: str | None) -> None:
+    """Update an asset by ID."""
+    client = ctx.get_client()
+    asset = {k: v for k, v in kwargs.items() if v is not None}
+    data = client.patch(f"assets/{id}", json={"asset": asset})
+    echo_output(data, fmt=ctx.output_format)
+
+
+@assets.command("delete")
+@click.argument("id")
+@click.confirmation_option(prompt="Are you sure you want to delete this asset?")
+@pass_context
+def delete_asset(ctx: Context, id: str) -> None:
+    """Delete an asset by ID."""
+    client = ctx.get_client()
+    client.delete(f"assets/{id}")
+    if not ctx.quiet:
+        click.echo(f"Asset {id} deleted.")

moneybird_cli/commands/contacts.py

@@ -0,0 +1,159 @@
+"""Contacts commands."""
+
+from __future__ import annotations
+
+import click
+
+from moneybird_cli.main import pass_context, Context
+from moneybird_cli.output import echo_output
+
+LIST_COLUMNS = ["id", "company_name", "firstname", "lastname", "email"]
+
+
+@click.group()
+def contacts() -> None:
+    """Manage contacts."""
+
+
+@contacts.command("list")
+@click.option("--all", "fetch_all", is_flag=True, help="Fetch all pages (respects rate limits).")
+@click.option("--page", type=int, default=None, help="Page number (default: 1).")
+@click.option("--per-page", type=int, default=None, help="Results per page (max 100).")
+@click.option("--include-archived", is_flag=True, help="Include archived contacts.")
+@pass_context
+def list_contacts(ctx: Context, fetch_all: bool, page: int | None, per_page: int | None, include_archived: bool) -> None:
+    """List contacts. Returns the first page by default; use --all to fetch everything."""
+    client = ctx.get_client()
+    params: dict = {}
+    if include_archived:
+        params["include_archived"] = "true"
+    if fetch_all:
+        data = client.get_all("contacts", params=params, per_page=per_page or 100)
+    else:
+        params["page"] = page or 1
+        if per_page:
+            params["per_page"] = per_page
+        data = client.get("contacts", params=params)
+    echo_output(data, fmt=ctx.output_format, columns=LIST_COLUMNS)
+
+
+@contacts.command("get")
+@click.argument("id")
+@pass_context
+def get_contact(ctx: Context, id: str) -> None:
+    """Get a single contact by ID."""
+    client = ctx.get_client()
+    data = client.get(f"contacts/{id}")
+    echo_output(data, fmt=ctx.output_format)
+
+
+@contacts.command("search")
+@click.argument("query")
+@pass_context
+def search_contacts(ctx: Context, query: str) -> None:
+    """Search contacts by name or email."""
+    client = ctx.get_client()
+    data = client.get_all("contacts", params={"query": query})
+    echo_output(data, fmt=ctx.output_format, columns=LIST_COLUMNS)
+
+
+@contacts.command("filter")
+@click.option("--created-after", help="Filter by creation date (ISO 8601).")
+@click.option("--updated-after", help="Filter by update date (ISO 8601).")
+@click.option("--first-name", help="Filter by first name.")
+@click.option("--last-name", help="Filter by last name.")
+@pass_context
+def filter_contacts(
+    ctx: Context,
+    created_after: str | None,
+    updated_after: str | None,
+    first_name: str | None,
+    last_name: str | None,
+) -> None:
+    """Filter contacts by criteria."""
+    client = ctx.get_client()
+    params: dict = {}
+    if created_after:
+        params["filter"] = f"created_after:{created_after}"
+    if updated_after:
+        params["filter"] = f"updated_after:{updated_after}"
+    if first_name:
+        params["filter"] = f"first_name:{first_name}"
+    if last_name:
+        params["filter"] = f"last_name:{last_name}"
+    data = client.get_all("contacts/filter", params=params)
+    echo_output(data, fmt=ctx.output_format, columns=LIST_COLUMNS)
+
+
+@contacts.command("create")
+@click.option("--company-name", help="Company name.")
+@click.option("--firstname", help="First name.")
+@click.option("--lastname", help="Last name.")
+@click.option("--email", help="Email address.")
+@click.option("--phone", help="Phone number.")
+@click.option("--address1", help="Address line 1.")
+@click.option("--address2", help="Address line 2.")
+@click.option("--zipcode", help="Zip code.")
+@click.option("--city", help="City.")
+@click.option("--country", help="Country code (e.g., NL).")
+@click.option("--delivery-method", type=click.Choice(["Email", "Simplerinvoicing", "Post", "Manual"]), help="Invoice delivery method.")
+@pass_context
+def create_contact(ctx: Context, **kwargs: str | None) -> None:
+    """Create a new contact."""
+    client = ctx.get_client()
+    contact = {k.replace("_", ""): v for k, v in kwargs.items() if v is not None}
+    # Map back to API field names
+    field_map = {
+        "companyname": "company_name",
+        "address1": "address1",
+        "address2": "address2",
+        "deliverymethod": "delivery_method",
+    }
+    api_contact = {}
+    for k, v in contact.items():
+        api_contact[field_map.get(k, k)] = v
+    data = client.post("contacts", json={"contact": api_contact})
+    echo_output(data, fmt=ctx.output_format)
+
+
+@contacts.command("update")
+@click.argument("id")
+@click.option("--company-name", help="Company name.")
+@click.option("--firstname", help="First name.")
+@click.option("--lastname", help="Last name.")
+@click.option("--email", help="Email address.")
+@click.option("--phone", help="Phone number.")
+@pass_context
+def update_contact(ctx: Context, id: str, **kwargs: str | None) -> None:
+    """Update a contact by ID."""
+    client = ctx.get_client()
+    contact = {k: v for k, v in kwargs.items() if v is not None}
+    field_map = {"company_name": "company_name"}
+    api_contact = {}
+    for k, v in contact.items():
+        api_contact[field_map.get(k, k)] = v
+    data = client.patch(f"contacts/{id}", json={"contact": api_contact})
+    echo_output(data, fmt=ctx.output_format)
+
+
+@contacts.command("delete")
+@click.argument("id")
+@click.confirmation_option(prompt="Are you sure you want to delete this contact?")
+@pass_context
+def delete_contact(ctx: Context, id: str) -> None:
+    """Delete a contact by ID."""
+    client = ctx.get_client()
+    client.delete(f"contacts/{id}")
+    if not ctx.quiet:
+        click.echo(f"Contact {id} deleted.")
+
+
+@contacts.command("archive")
+@click.argument("id")
+@pass_context
+def archive_contact(ctx: Context, id: str) -> None:
+    """Archive a contact by ID."""
+    client = ctx.get_client()
+    client.patch(f"contacts/{id}/archive")
+    if not ctx.quiet:
+        click.echo(f"Contact {id} archived.")

moneybird_cli/commands/documents.py

@@ -0,0 +1,226 @@
+"""Document commands (general, journal, purchase invoices, receipts, typeless)."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+import click
+
+from moneybird_cli.main import pass_context, Context
+from moneybird_cli.output import echo_output
+
+
+def _list_cmd(api_path: str, list_columns: list[str]) -> Callable:
+    @click.command("list")
+    @click.option("--all", "fetch_all", is_flag=True, help="Fetch all pages (respects rate limits).")
+    @click.option("--period", help="Filter by period (e.g., this_month, prev_year, 202401..202412).")
+    @click.option("--page", type=int, default=None, help="Page number (default: 1).")
+    @click.option("--per-page", type=int, default=None, help="Results per page (max 100).")
+    @pass_context
+    def cmd(ctx: Context, fetch_all: bool, period: str | None, page: int | None, per_page: int | None) -> None:
+        """List documents. Returns the first page by default; use --all to fetch everything."""
+        client = ctx.get_client()
+        params: dict = {}
+        if period:
+            params["filter"] = f"period:{period}"
+        if fetch_all:
+            data = client.get_all(api_path, params=params, per_page=per_page or 100)
+        else:
+            params["page"] = page or 1
+            if per_page:
+                params["per_page"] = per_page
+            data = client.get(api_path, params=params)
+        echo_output(data, fmt=ctx.output_format, columns=list_columns)
+    return cmd
+
+
+def _get_cmd(api_path: str) -> Callable:
+    @click.command("get")
+    @click.argument("id")
+    @pass_context
+    def cmd(ctx: Context, id: str) -> None:
+        """Get a single document by ID."""
+        client = ctx.get_client()
+        data = client.get(f"{api_path}/{id}")
+        echo_output(data, fmt=ctx.output_format)
+    return cmd
+
+
+def _delete_cmd(api_path: str) -> Callable:
+    @click.command("delete")
+    @click.argument("id")
+    @click.confirmation_option(prompt="Are you sure you want to delete this document?")
+    @pass_context
+    def cmd(ctx: Context, id: str) -> None:
+        """Delete a document by ID."""
+        client = ctx.get_client()
+        client.delete(f"{api_path}/{id}")
+        if not ctx.quiet:
+            click.echo(f"Document {id} deleted.")
+    return cmd
+
+
+# --- General Documents ---
+
+@click.group(name="general-documents")
+def general_documents() -> None:
+    """Manage general documents."""
+
+general_documents.add_command(_list_cmd("documents/general_documents", ["id", "contact_id", "reference", "date", "state"]))
+general_documents.add_command(_get_cmd("documents/general_documents"))
+general_documents.add_command(_delete_cmd("documents/general_documents"))
+
+@general_documents.command("create")
+@click.option("--contact-id", required=True, help="Contact ID.")
+@click.option("--reference", help="Document reference.")
+@click.option("--date", help="Document date (YYYY-MM-DD).")
+@click.option("--due-date", help="Due date (YYYY-MM-DD).")
+@pass_context
+def create_general_document(ctx: Context, **kwargs: str | None) -> None:
+    """Create a new general document."""
+    client = ctx.get_client()
+    doc = {k: v for k, v in kwargs.items() if v is not None}
+    data = client.post("documents/general_documents", json={"general_document": doc})
+    echo_output(data, fmt=ctx.output_format)
+
+@general_documents.command("update")
+@click.argument("id")
+@click.option("--reference", help="Document reference.")
+@click.option("--date", help="Document date (YYYY-MM-DD).")
+@click.option("--due-date", help="Due date (YYYY-MM-DD).")
+@pass_context
+def update_general_document(ctx: Context, id: str, **kwargs: str | None) -> None:
+    """Update a general document by ID."""
+    client = ctx.get_client()
+    doc = {k: v for k, v in kwargs.items() if v is not None}
+    data = client.patch(f"documents/general_documents/{id}", json={"general_document": doc})
+    echo_output(data, fmt=ctx.output_format)
+
+
+# --- General Journal Documents ---
+
+@click.group(name="journal-documents")
+def general_journal_documents() -> None:
+    """Manage general journal documents."""
+
+general_journal_documents.add_command(_list_cmd("documents/general_journal_documents", ["id", "reference", "date", "journal_type"]))
+general_journal_documents.add_command(_get_cmd("documents/general_journal_documents"))
+general_journal_documents.add_command(_delete_cmd("documents/general_journal_documents"))
+
+@general_journal_documents.command("create")
+@click.option("--reference", help="Document reference.")
+@click.option("--date", help="Document date (YYYY-MM-DD).")
+@pass_context
+def create_journal_document(ctx: Context, **kwargs: str | None) -> None:
+    """Create a new general journal document."""
+    client = ctx.get_client()
+    doc = {k: v for k, v in kwargs.items() if v is not None}
+    data = client.post("documents/general_journal_documents", json={"general_journal_document": doc})
+    echo_output(data, fmt=ctx.output_format)
+
+@general_journal_documents.command("update")
+@click.argument("id")
+@click.option("--reference", help="Document reference.")
+@click.option("--date", help="Document date (YYYY-MM-DD).")
+@pass_context
+def update_journal_document(ctx: Context, id: str, **kwargs: str | None) -> None:
+    """Update a general journal document by ID."""
+    client = ctx.get_client()
+    doc = {k: v for k, v in kwargs.items() if v is not None}
+    data = client.patch(f"documents/general_journal_documents/{id}", json={"general_journal_document": doc})
+    echo_output(data, fmt=ctx.output_format)
+
+
+# --- Purchase Invoices ---
+
+@click.group(name="purchase-invoices")
+def purchase_invoices() -> None:
+    """Manage purchase invoices."""
+
+purchase_invoices.add_command(_list_cmd("documents/purchase_invoices", ["id", "contact_id", "reference", "date", "state", "total_price_incl_tax"]))
+purchase_invoices.add_command(_get_cmd("documents/purchase_invoices"))
+purchase_invoices.add_command(_delete_cmd("documents/purchase_invoices"))
+
+@purchase_invoices.command("create")
+@click.option("--contact-id", required=True, help="Contact ID.")
+@click.option("--reference", help="Invoice reference.")
+@click.option("--date", help="Invoice date (YYYY-MM-DD).")
+@click.option("--due-date", help="Due date (YYYY-MM-DD).")
+@click.option("--currency", help="Currency code (default: EUR).")
+@pass_context
+def create_purchase_invoice(ctx: Context, **kwargs: str | None) -> None:
+    """Create a new purchase invoice."""
+    client = ctx.get_client()
+    doc = {k: v for k, v in kwargs.items() if v is not None}
+    data = client.post("documents/purchase_invoices", json={"purchase_invoice": doc})
+    echo_output(data, fmt=ctx.output_format)
+
+@purchase_invoices.command("update")
+@click.argument("id")
+@click.option("--reference", help="Invoice reference.")
+@click.option("--date", help="Invoice date (YYYY-MM-DD).")
+@click.option("--due-date", help="Due date (YYYY-MM-DD).")
+@pass_context
+def update_purchase_invoice(ctx: Context, id: str, **kwargs: str | None) -> None:
+    """Update a purchase invoice by ID."""
+    client = ctx.get_client()
+    doc = {k: v for k, v in kwargs.items() if v is not None}
+    data = client.patch(f"documents/purchase_invoices/{id}", json={"purchase_invoice": doc})
+    echo_output(data, fmt=ctx.output_format)
+
+
+# --- Receipts ---
+
+@click.group(name="receipts")
+def receipts() -> None:
+    """Manage receipts."""
+
+receipts.add_command(_list_cmd("documents/receipts", ["id", "contact_id", "reference", "date", "state", "total_price_incl_tax"]))
+receipts.add_command(_get_cmd("documents/receipts"))
+receipts.add_command(_delete_cmd("documents/receipts"))
+
+@receipts.command("create")
+@click.option("--contact-id", required=True, help="Contact ID.")
+@click.option("--reference", help="Receipt reference.")
+@click.option("--date", help="Receipt date (YYYY-MM-DD).")
+@pass_context
+def create_receipt(ctx: Context, **kwargs: str | None) -> None:
+    """Create a new receipt."""
+    client = ctx.get_client()
+    doc = {k: v for k, v in kwargs.items() if v is not None}
+    data = client.post("documents/receipts", json={"receipt": doc})
+    echo_output(data, fmt=ctx.output_format)
+
+@receipts.command("update")
+@click.argument("id")
+@click.option("--reference", help="Receipt reference.")
+@click.option("--date", help="Receipt date (YYYY-MM-DD).")
+@pass_context
+def update_receipt(ctx: Context, id: str, **kwargs: str | None) -> None:
+    """Update a receipt by ID."""
+    client = ctx.get_client()
+    doc = {k: v for k, v in kwargs.items() if v is not None}
+    data = client.patch(f"documents/receipts/{id}", json={"receipt": doc})
+    echo_output(data, fmt=ctx.output_format)
+
+
+# --- Typeless Documents ---
+
+@click.group(name="typeless-documents")
+def typeless_documents() -> None:
+    """Manage typeless documents (unclassified uploads)."""
+
+typeless_documents.add_command(_list_cmd("documents/typeless_documents", ["id", "contact_id", "reference", "date", "state"]))
+typeless_documents.add_command(_get_cmd("documents/typeless_documents"))
+typeless_documents.add_command(_delete_cmd("documents/typeless_documents"))
+
+@typeless_documents.command("create")
+@click.option("--contact-id", help="Contact ID.")
+@click.option("--reference", help="Document reference.")
+@pass_context
+def create_typeless_document(ctx: Context, **kwargs: str | None) -> None:
+    """Create a new typeless document."""
+    client = ctx.get_client()
+    doc = {k: v for k, v in kwargs.items() if v is not None}
+    data = client.post("documents/typeless_documents", json={"typeless_document": doc})
+    echo_output(data, fmt=ctx.output_format)