lxw-cli 0.1.3__tar.gz → 0.4.0__tar.gz

{lxw_cli-0.1.3 → lxw_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lxw-cli
-Version: 0.1.3
+Version: 0.4.0
 Summary: Inoffizielles CLI/TUI/MCP-Tool für die Lexware Office API (vormals lexoffice)
 Project-URL: Homepage, https://github.com/OEM-Mrks/lxw-cli
 Project-URL: Documentation, https://developers.lexware.io/
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Office/Business :: Financial :: Accounting
 Requires-Python: >=3.11
+Requires-Dist: cryptography>=42
 Requires-Dist: fastmcp>=2.10
 Requires-Dist: httpx>=0.27
 Requires-Dist: pydantic>=2.6
@@ -97,10 +98,11 @@ lxw --version                  # Kontrolle
 ```
 
 Sieht uv eine frisch veröffentlichte Version noch nicht (das PyPI-CDN braucht
-nach einem Release ein paar Minuten), erzwingt `--refresh` den Index-Abgleich:
+nach einem Release ein paar Minuten) oder ist das Tool auf eine exakte Version
+gepinnt, hilft ein Neu-Install auf `latest`:
 
 ```bash
-uv tool upgrade --refresh lxw-cli
+uv tool install --force lxw-cli@latest
 ```
 
 Der MCP-Server für Claude nutzt das Update automatisch mit — bereits laufende
@@ -405,11 +407,21 @@ Claude erkennt die Tools automatisch und ruft sie auf.
 
 ### Verfügbare MCP-Tools
 
-26 Tools mit identischem Verhalten wie die CLI-Befehle:
+31 Tools mit identischem Verhalten wie die CLI-Befehle:
 
+- **Info**: `version` (meldet die laufende Version + Build-Zeitstempel — nützlich, wenn eine Client-UI wie ChatGPT eine gecachte/alte Version anzeigt)
+- **Belegkette (weiterführen)**: `continue_document` führt einen Beleg in den Folgebeleg fort und hält beide verknüpft (`precedingSalesVoucherId`). Der Quelltyp wird automatisch erkannt (Belegnummer oder id). Unterstützte Wege (wie in Lexware):
+  - **Angebot** → Auftrag · Lieferschein · Rechnung
+  - **Auftrag** → Lieferschein · Rechnung
+  - **Lieferschein** → Rechnung
+  - **Rechnung** → Lieferschein · Rechnungskorrektur
+
+  Inhalte (Kunde, Positionen, Texte) werden übernommen, der Folgebeleg entsteht als Entwurf. Für Rechnung/Rechnungskorrektur muss der Ausgangsbeleg **festgeschrieben** sein (sonst klare Meldung statt HTTP 406). **Abschlagsrechnung** und **Serienrechnung** sind über die Lexware-API nicht erstellbar — das meldet das Tool klar.
 - **Lesen**: `profile`, `list_invoices`, `get_invoice`, `download_invoice_pdf`, `list_contacts`, `get_contact`, `list_vouchers`, `get_voucher`, `list_articles`, `get_article`, `list_quotations`, `get_quotation`, `download_quotation_pdf`, `list_order_confirmations`, `get_order_confirmation`, `download_order_confirmation_pdf`, `list_delivery_notes`, `get_delivery_note`, `download_delivery_note_pdf`
 - **Belege als Draft anlegen**: `create_invoice_draft`, `create_voucher_draft`, `create_quotation_draft`, `create_order_confirmation_draft`, `create_delivery_note_draft`
 - **Stammdaten anlegen** (kein Draft): `create_contact`, `create_article`
+- **Stammdaten bearbeiten** (Teil-Update mit Auto-Merge + automatischem `version`-Handling): `update_contact`, `update_article`. Es werden nur die übergebenen Felder geändert; verschachtelte Objekte werden feldweise zusammengeführt, Listen komplett ersetzt. (Kontakt-`archived` ist in der Lexware-API read-only und kann nicht per API gesetzt werden. Firmen-Kontakte mit **mehr als einem Ansprechpartner** lassen sich per Lexware-API grundsätzlich nicht aktualisieren — `update_contact` meldet das klar, statt eines rohen HTTP 406.)
+- **Funktionswunsch melden**: `request_feature` erstellt einen **unverbindlichen** Feature-Wunsch als fertigen Text (`subject`/`body`) samt Anbieter-Adresse (`to` = david@oemedia.de). Der Server **versendet nichts** — der Nutzer kopiert den Text und schickt ihn selbst per E-Mail. Dies ist ein Endkundenprodukt: der Assistent baut keine Funktionen selbst, sondern bietet bei fehlenden Funktionen nur diesen Weg an.
 
 Alle document-Tools (`get_*`, `download_*_pdf`) akzeptieren UUID **oder** Belegnummer (z.B. `FB2600682`). PDFs landen in `~/Downloads/lexware/`.
 
@@ -431,6 +443,55 @@ lxw mcp uninstall-desktop         # aus Claude Desktop entfernen
 lxw mcp serve                     # läuft direkt — wird von Claude intern aufgerufen
 ```
 
+### Multi-User-Server (HTTP) — ein Server, jeder mit eigenem Key
+
+Neben dem lokalen stdio-Modus gibt es `lxw-mcp-http`: einen zentralen
+MCP-Server für mehrere Nutzer, bei dem **jeder seinen eigenen Lexware-API-Key
+mitbringt**. Der Server speichert keine Keys — er ist ein zustandsloser Proxy.
+
+```bash
+LXW_MCP_PUBLIC_URL=https://mcp.example.com \
+LXW_MCP_SECRET='ein-langes-zufaelliges-secret' \
+lxw-mcp-http    # lauscht auf 127.0.0.1:8788 (LXW_MCP_HOST/LXW_MCP_PORT)
+```
+
+Zwei Wege, den eigenen Key mitzubringen:
+
+1. **Direkt als Bearer-Header** (Claude Code, Cursor, Skripte — alles, was
+   eigene Header kann). Der Key bleibt in der lokalen Client-Config:
+
+   ```bash
+   claude mcp add lexware --transport http https://mcp.example.com/mcp \
+     --header "Authorization: Bearer ${LEXWARE_API_KEY}"
+   ```
+
+2. **OAuth** (claude.ai, ChatGPT — Clients ohne Header-Support): Beim
+   Verbinden öffnet sich eine Consent-Seite des Servers, auf der man einmalig
+   seinen Lexware-Key eingibt. Der Server prüft ihn gegen die Lexware-API und
+   stellt ein Zugriffstoken aus, in dem der Key **verschlüsselt eingebettet**
+   ist (Fernet, `LXW_MCP_SECRET`). Das Token liegt beim Client auf dem Gerät
+   des Nutzers; der Server entschlüsselt es nur pro Request und persistiert
+   ausschließlich die OAuth-Client-Registrierungen (`LXW_MCP_DATA_DIR`,
+   Standard `~/.config/lexware/mcp/`).
+
+Hinweise für den Betrieb:
+
+- `LXW_MCP_SECRET` **fest setzen** — ohne festes Secret werden alle Tokens
+  bei jedem Neustart ungültig. Rotieren des Secrets invalidiert bewusst alle
+  ausgestellten Tokens.
+- Vor den Server gehört ein HTTPS-Reverse-Proxy (Caddy, nginx, Cloudflare
+  Tunnel, `tailscale serve`, …); `LXW_MCP_PUBLIC_URL` ist die von außen
+  sichtbare Basis-URL (sie steht in den OAuth-Metadaten).
+- PDF-Downloads liefern über HTTP das PDF als Binärinhalt zurück (statt eines
+  Pfads auf der Server-Platte wie im stdio-Modus).
+- Tokens laufen nach 24 h ab; Clients erneuern sie automatisch per
+  Refresh-Token. Ein geleaktes Token wird wirkungslos, sobald der zugehörige
+  Lexware-Key unter <https://app.lexware.de/addons/public-api> widerrufen wird.
+
+`request_feature` braucht keine Konfiguration: es liefert nur einen fertigen
+Text + die Empfänger-Adresse (`david@oemedia.de`) zurück, den der Nutzer selbst
+per E-Mail sendet. Der Server verschickt nichts.
+
 ## Out of Scope (v1)
 
 Bewusst nicht enthalten:

{lxw_cli-0.1.3 → lxw_cli-0.4.0}/README.md

@@ -62,10 +62,11 @@ lxw --version                  # Kontrolle
 ```
 
 Sieht uv eine frisch veröffentlichte Version noch nicht (das PyPI-CDN braucht
-nach einem Release ein paar Minuten), erzwingt `--refresh` den Index-Abgleich:
+nach einem Release ein paar Minuten) oder ist das Tool auf eine exakte Version
+gepinnt, hilft ein Neu-Install auf `latest`:
 
 ```bash
-uv tool upgrade --refresh lxw-cli
+uv tool install --force lxw-cli@latest
 ```
 
 Der MCP-Server für Claude nutzt das Update automatisch mit — bereits laufende
@@ -370,11 +371,21 @@ Claude erkennt die Tools automatisch und ruft sie auf.
 
 ### Verfügbare MCP-Tools
 
-26 Tools mit identischem Verhalten wie die CLI-Befehle:
+31 Tools mit identischem Verhalten wie die CLI-Befehle:
 
+- **Info**: `version` (meldet die laufende Version + Build-Zeitstempel — nützlich, wenn eine Client-UI wie ChatGPT eine gecachte/alte Version anzeigt)
+- **Belegkette (weiterführen)**: `continue_document` führt einen Beleg in den Folgebeleg fort und hält beide verknüpft (`precedingSalesVoucherId`). Der Quelltyp wird automatisch erkannt (Belegnummer oder id). Unterstützte Wege (wie in Lexware):
+  - **Angebot** → Auftrag · Lieferschein · Rechnung
+  - **Auftrag** → Lieferschein · Rechnung
+  - **Lieferschein** → Rechnung
+  - **Rechnung** → Lieferschein · Rechnungskorrektur
+
+  Inhalte (Kunde, Positionen, Texte) werden übernommen, der Folgebeleg entsteht als Entwurf. Für Rechnung/Rechnungskorrektur muss der Ausgangsbeleg **festgeschrieben** sein (sonst klare Meldung statt HTTP 406). **Abschlagsrechnung** und **Serienrechnung** sind über die Lexware-API nicht erstellbar — das meldet das Tool klar.
 - **Lesen**: `profile`, `list_invoices`, `get_invoice`, `download_invoice_pdf`, `list_contacts`, `get_contact`, `list_vouchers`, `get_voucher`, `list_articles`, `get_article`, `list_quotations`, `get_quotation`, `download_quotation_pdf`, `list_order_confirmations`, `get_order_confirmation`, `download_order_confirmation_pdf`, `list_delivery_notes`, `get_delivery_note`, `download_delivery_note_pdf`
 - **Belege als Draft anlegen**: `create_invoice_draft`, `create_voucher_draft`, `create_quotation_draft`, `create_order_confirmation_draft`, `create_delivery_note_draft`
 - **Stammdaten anlegen** (kein Draft): `create_contact`, `create_article`
+- **Stammdaten bearbeiten** (Teil-Update mit Auto-Merge + automatischem `version`-Handling): `update_contact`, `update_article`. Es werden nur die übergebenen Felder geändert; verschachtelte Objekte werden feldweise zusammengeführt, Listen komplett ersetzt. (Kontakt-`archived` ist in der Lexware-API read-only und kann nicht per API gesetzt werden. Firmen-Kontakte mit **mehr als einem Ansprechpartner** lassen sich per Lexware-API grundsätzlich nicht aktualisieren — `update_contact` meldet das klar, statt eines rohen HTTP 406.)
+- **Funktionswunsch melden**: `request_feature` erstellt einen **unverbindlichen** Feature-Wunsch als fertigen Text (`subject`/`body`) samt Anbieter-Adresse (`to` = david@oemedia.de). Der Server **versendet nichts** — der Nutzer kopiert den Text und schickt ihn selbst per E-Mail. Dies ist ein Endkundenprodukt: der Assistent baut keine Funktionen selbst, sondern bietet bei fehlenden Funktionen nur diesen Weg an.
 
 Alle document-Tools (`get_*`, `download_*_pdf`) akzeptieren UUID **oder** Belegnummer (z.B. `FB2600682`). PDFs landen in `~/Downloads/lexware/`.
 
@@ -396,6 +407,55 @@ lxw mcp uninstall-desktop         # aus Claude Desktop entfernen
 lxw mcp serve                     # läuft direkt — wird von Claude intern aufgerufen
 ```
 
+### Multi-User-Server (HTTP) — ein Server, jeder mit eigenem Key
+
+Neben dem lokalen stdio-Modus gibt es `lxw-mcp-http`: einen zentralen
+MCP-Server für mehrere Nutzer, bei dem **jeder seinen eigenen Lexware-API-Key
+mitbringt**. Der Server speichert keine Keys — er ist ein zustandsloser Proxy.
+
+```bash
+LXW_MCP_PUBLIC_URL=https://mcp.example.com \
+LXW_MCP_SECRET='ein-langes-zufaelliges-secret' \
+lxw-mcp-http    # lauscht auf 127.0.0.1:8788 (LXW_MCP_HOST/LXW_MCP_PORT)
+```
+
+Zwei Wege, den eigenen Key mitzubringen:
+
+1. **Direkt als Bearer-Header** (Claude Code, Cursor, Skripte — alles, was
+   eigene Header kann). Der Key bleibt in der lokalen Client-Config:
+
+   ```bash
+   claude mcp add lexware --transport http https://mcp.example.com/mcp \
+     --header "Authorization: Bearer ${LEXWARE_API_KEY}"
+   ```
+
+2. **OAuth** (claude.ai, ChatGPT — Clients ohne Header-Support): Beim
+   Verbinden öffnet sich eine Consent-Seite des Servers, auf der man einmalig
+   seinen Lexware-Key eingibt. Der Server prüft ihn gegen die Lexware-API und
+   stellt ein Zugriffstoken aus, in dem der Key **verschlüsselt eingebettet**
+   ist (Fernet, `LXW_MCP_SECRET`). Das Token liegt beim Client auf dem Gerät
+   des Nutzers; der Server entschlüsselt es nur pro Request und persistiert
+   ausschließlich die OAuth-Client-Registrierungen (`LXW_MCP_DATA_DIR`,
+   Standard `~/.config/lexware/mcp/`).
+
+Hinweise für den Betrieb:
+
+- `LXW_MCP_SECRET` **fest setzen** — ohne festes Secret werden alle Tokens
+  bei jedem Neustart ungültig. Rotieren des Secrets invalidiert bewusst alle
+  ausgestellten Tokens.
+- Vor den Server gehört ein HTTPS-Reverse-Proxy (Caddy, nginx, Cloudflare
+  Tunnel, `tailscale serve`, …); `LXW_MCP_PUBLIC_URL` ist die von außen
+  sichtbare Basis-URL (sie steht in den OAuth-Metadaten).
+- PDF-Downloads liefern über HTTP das PDF als Binärinhalt zurück (statt eines
+  Pfads auf der Server-Platte wie im stdio-Modus).
+- Tokens laufen nach 24 h ab; Clients erneuern sie automatisch per
+  Refresh-Token. Ein geleaktes Token wird wirkungslos, sobald der zugehörige
+  Lexware-Key unter <https://app.lexware.de/addons/public-api> widerrufen wird.
+
+`request_feature` braucht keine Konfiguration: es liefert nur einen fertigen
+Text + die Empfänger-Adresse (`david@oemedia.de`) zurück, den der Nutzer selbst
+per E-Mail sendet. Der Server verschickt nichts.
+
 ## Out of Scope (v1)
 
 Bewusst nicht enthalten:

{lxw_cli-0.1.3 → lxw_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lxw-cli"
-version = "0.1.3"
+version = "0.4.0"
 description = "Inoffizielles CLI/TUI/MCP-Tool für die Lexware Office API (vormals lexoffice)"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -30,6 +30,7 @@ dependencies = [
     "python-dotenv>=1.0",
     "fastmcp>=2.10",
     "textual>=0.58",
+    "cryptography>=42",
 ]
 
 [project.optional-dependencies]
@@ -44,6 +45,7 @@ dev = [
 [project.scripts]
 lxw = "lxw_cli.cli:_run"
 lxw-mcp = "lxw_cli.mcp_server:run"
+lxw-mcp-http = "lxw_cli.mcp_server:run_http"
 lxw-tui = "lxw_cli.tui.app:run"
 
 [project.urls]

{lxw_cli-0.1.3 → lxw_cli-0.4.0}/src/lxw_cli/core/client.py

@@ -125,8 +125,10 @@ class LexwareClient:
     def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
         return self._request("GET", path, params=params).json()
 
-    def post(self, path: str, json_body: Any) -> Any:
-        return self._request("POST", path, json=json_body).json()
+    def post(
+        self, path: str, json_body: Any, params: dict[str, Any] | None = None
+    ) -> Any:
+        return self._request("POST", path, params=params, json=json_body).json()
 
     def put(self, path: str, json_body: Any) -> Any:
         return self._request("PUT", path, json=json_body).json()

{lxw_cli-0.1.3 → lxw_cli-0.4.0}/src/lxw_cli/core/services.py

@@ -500,6 +500,263 @@ def create_delivery_note(
     return client.post("/v1/delivery-notes", body)
 
 
+# -- Belegkette: einen Beleg in den Folgebeleg fortführen (pursue) -----------
+
+# Human labels + the resource endpoint per document type.
+_DOC_META: dict[str, dict[str, str]] = {
+    "quotation": {"label": "Angebot", "path": "/v1/quotations/{id}"},
+    "orderconfirmation": {"label": "Auftrag", "path": "/v1/order-confirmations/{id}"},
+    "deliverynote": {"label": "Lieferschein", "path": "/v1/delivery-notes/{id}"},
+    "invoice": {"label": "Rechnung", "path": "/v1/invoices/{id}"},
+    "creditnote": {"label": "Rechnungskorrektur", "path": "/v1/credit-notes/{id}"},
+}
+
+# The follow-up transitions Lexware's API supports (mirrors the web app's
+# "Weiterführen" menu). Nested: source type -> target type -> create endpoint.
+# Abschlagsrechnung (down payment) and Serienrechnung are intentionally absent —
+# the API cannot create those (down payment invoices are read-only).
+_PURSUE_MATRIX: dict[str, dict[str, str]] = {
+    "quotation": {
+        "orderconfirmation": "/v1/order-confirmations",
+        "deliverynote": "/v1/delivery-notes",
+        "invoice": "/v1/invoices",
+    },
+    "orderconfirmation": {
+        "deliverynote": "/v1/delivery-notes",
+        "invoice": "/v1/invoices",
+    },
+    "deliverynote": {
+        "invoice": "/v1/invoices",
+    },
+    "invoice": {
+        "deliverynote": "/v1/delivery-notes",
+        "creditnote": "/v1/credit-notes",
+    },
+}
+
+# Map human/German synonyms (and API type strings) to a normalized target type.
+_TARGET_ALIASES = {
+    "auftrag": "orderconfirmation",
+    "auftragsbestätigung": "orderconfirmation",
+    "auftragsbestaetigung": "orderconfirmation",
+    "orderconfirmation": "orderconfirmation",
+    "order_confirmation": "orderconfirmation",
+    "order-confirmation": "orderconfirmation",
+    "lieferschein": "deliverynote",
+    "deliverynote": "deliverynote",
+    "delivery_note": "deliverynote",
+    "rechnung": "invoice",
+    "invoice": "invoice",
+    "rechnungskorrektur": "creditnote",
+    "gutschrift": "creditnote",
+    "korrektur": "creditnote",
+    "creditnote": "creditnote",
+    "credit_note": "creditnote",
+}
+
+# Targets a user may ask for that the API cannot create (only the web app can).
+_TARGET_UNSUPPORTED = {
+    "abschlagsrechnung": "Abschlagsrechnung",
+    "downpaymentinvoice": "Abschlagsrechnung",
+    "down_payment_invoice": "Abschlagsrechnung",
+    "serienrechnung": "Serienrechnung",
+    "recurring": "Serienrechnung",
+}
+
+# voucherlist reports finalized invoices as "salesinvoice"; normalize to our key.
+_SOURCE_TYPE_NORMALIZE = {"salesinvoice": "invoice"}
+
+# Server-managed / computed fields, plus type-specific fields that must not be
+# carried into the follow-up (e.g. a quotation's expirationDate has no place on
+# an order confirmation or invoice).
+_PURSUE_DROP_DOC = {
+    "id",
+    "organizationId",
+    "version",
+    "voucherNumber",
+    "voucherStatus",
+    "createdDate",
+    "updatedDate",
+    "files",
+    "relatedVouchers",
+    "archived",
+    "taxAmounts",
+    "expirationDate",
+    "electronicDocumentProfile",
+}
+_PURSUE_DROP_LINEITEM = {"id", "lineItemAmount"}
+
+
+def continue_document(
+    client: LexwareClient, identifier: str, target: str
+) -> dict[str, Any]:
+    """Continue a sales voucher into its follow-up, preserving the chain.
+
+    Detects the source document's type from `identifier` (UUID or voucher
+    number), copies its content into a fresh draft of `target`, and POSTs it
+    with ``precedingSalesVoucherId`` so Lexware links both in the Belegkette.
+    Supported transitions mirror the Lexware web app (Angebot→Auftrag/
+    Lieferschein/Rechnung, Auftrag→Lieferschein/Rechnung, Lieferschein→Rechnung,
+    Rechnung→Lieferschein/Rechnungskorrektur). Invalid or unsupported steps are
+    reported clearly instead of as a raw HTTP 406.
+    """
+    raw = target.strip().lower()
+    if raw in _TARGET_UNSUPPORTED:
+        name = _TARGET_UNSUPPORTED[raw]
+        raise LexwareError(
+            f"{name} kann über die Schnittstelle nicht erstellt werden — das geht "
+            "nur direkt in Lexware."
+        )
+    target_type = _TARGET_ALIASES.get(raw)
+    if target_type is None:
+        raise LexwareError(
+            f"Unbekanntes Ziel '{target}'. Möglich sind: Auftrag, Lieferschein, "
+            "Rechnung oder Rechnungskorrektur."
+        )
+
+    source_type, source_id, source = _resolve_source(client, identifier)
+    allowed = _PURSUE_MATRIX.get(source_type, {})
+    target_path = allowed.get(target_type)
+    if target_path is None:
+        from_label = _DOC_META.get(source_type, {}).get("label", source_type)
+        options = ", ".join(_DOC_META[t]["label"] for t in allowed) or "keine"
+        raise LexwareError(
+            f"Ein {from_label} kann nicht zu '{_DOC_META[target_type]['label']}' "
+            f"weitergeführt werden. Von hier möglich: {options}."
+        )
+
+    body = _pursue_body(source)
+    try:
+        return client.post(
+            target_path, body, params={"precedingSalesVoucherId": source_id}
+        )
+    except LexwareAPIError as exc:
+        if exc.status_code in (400, 406):
+            raise LexwareError(
+                _pursue_error(exc, source_type, target_type)
+            ) from exc
+        raise
+
+
+def _resolve_source(
+    client: LexwareClient, identifier: str
+) -> tuple[str, str, dict[str, Any]]:
+    """Determine a source document's (normalized type, id, full body).
+
+    A voucher number is looked up in the voucherlist (which reports the type).
+    A UUID is probed against each sales-voucher endpoint until one answers.
+    """
+    ident = identifier.strip()
+    if _looks_like_uuid(ident):
+        for source_type, meta in _DOC_META.items():
+            try:
+                doc = client.get(meta["path"].format(id=ident))
+            except LexwareAPIError as exc:
+                if exc.status_code == 404:
+                    continue
+                raise
+            return source_type, ident, doc
+        raise LexwareError(
+            f"Kein Beleg mit der ID '{identifier}' gefunden."
+        )
+
+    # Voucher number: the voucherlist row carries the type and the real id.
+    result = client.get(
+        "/v1/voucherlist",
+        params={
+            "voucherNumber": ident,
+            "voucherType": ALL_VOUCHER_TYPES,  # already a comma-joined string
+            "voucherStatus": "any",
+            "size": 2,
+        },
+    )
+    rows = result.get("content") or []
+    if not rows:
+        raise LexwareError(f"Kein Beleg mit Nummer '{identifier}' gefunden.")
+    row = rows[0]
+    raw_type = row.get("voucherType", "")
+    source_type = _SOURCE_TYPE_NORMALIZE.get(raw_type, raw_type)
+    meta = _DOC_META.get(source_type)
+    if meta is None:
+        raise LexwareError(
+            f"Belegtyp '{raw_type}' von '{identifier}' kann nicht weitergeführt "
+            "werden."
+        )
+    doc = get_with_voucher_fallback(client, meta["path"].format(id=row["id"]))
+    return source_type, row["id"], doc
+
+
+def _looks_like_uuid(value: str) -> bool:
+    parts = value.split("-")
+    return len(parts) == 5 and all(
+        c in "0123456789abcdefABCDEF" for c in value.replace("-", "")
+    )
+
+
+def _pursue_error(exc: LexwareAPIError, source_type: str, target_type: str) -> str:
+    """Turn a 400/406 from a pursue POST into a clear German message.
+
+    Lexware uses 406 for three cases: body validation (with a `details` list),
+    a not-yet-finalized preceding document, and a plain invalid transition.
+    Surface the most specific explanation available.
+    """
+    to_label = _DOC_META[target_type]["label"]
+    from_label = _DOC_META.get(source_type, {}).get("label", source_type)
+    body = exc.body if isinstance(exc.body, dict) else {}
+
+    details = body.get("details")
+    if details:
+        parts = [
+            f"{d.get('field', '?')}: {d.get('message', '')}".strip(": ")
+            for d in details
+            if isinstance(d, dict)
+        ]
+        joined = "; ".join(p for p in parts if p)
+        if joined:
+            return f"Weiterführen zu '{to_label}' nicht möglich: {joined}."
+
+    message = (body.get("message") or "").strip()
+    if "finali" in message.lower():
+        return (
+            f"Der Ausgangsbeleg ({from_label}) ist noch ein Entwurf. Er muss in "
+            f"Lexware erst festgeschrieben werden, bevor er zu '{to_label}' "
+            "weitergeführt werden kann."
+        )
+    if message:
+        return f"Weiterführen zu '{to_label}' nicht möglich: {message}"
+
+    return (
+        f"Dieser {from_label} lässt sich gerade nicht zu '{to_label}' weiterführen "
+        "(z. B. weil er storniert oder bereits weitergeführt ist)."
+    )
+
+
+def _pursue_body(source: dict[str, Any]) -> dict[str, Any]:
+    """Turn a fetched document into a fresh create-body for its follow-up.
+
+    Drops server-managed/computed fields, re-dates the document to today, keeps
+    only the currency on ``totalPrice`` (amounts are recomputed server-side),
+    and strips per-line-item ids/amounts. Content (address, line items, tax /
+    shipping / payment conditions, texts, language) carries over unchanged.
+    """
+    body = {k: v for k, v in source.items() if k not in _PURSUE_DROP_DOC}
+    body["voucherDate"] = datetime.now().astimezone().isoformat(timespec="milliseconds")
+    body["lineItems"] = [
+        {k: v for k, v in item.items() if k not in _PURSUE_DROP_LINEITEM}
+        for item in (body.get("lineItems") or [])
+    ]
+    currency = (source.get("totalPrice") or {}).get("currency", "EUR")
+    body["totalPrice"] = {"currency": currency}
+    # Ensure the follow-up's required blocks exist even when the source type
+    # doesn't carry them (a quotation has no shippingConditions, but an order
+    # confirmation / invoice requires one).
+    if not body.get("taxConditions"):
+        body["taxConditions"] = {"taxType": "net"}
+    if not body.get("shippingConditions"):
+        body["shippingConditions"] = {"shippingType": "none"}
+    return body
+
+
 # -- Contacts ---------------------------------------------------------------
 
 
@@ -554,6 +811,44 @@ def create_contact(client: LexwareClient, body: dict[str, Any]) -> dict[str, Any
     return client.post("/v1/contacts", body)
 
 
+def update_contact(
+    client: LexwareClient, contact_id: str, changes: dict[str, Any]
+) -> dict[str, Any]:
+    """Partially update a contact: fetch, deep-merge, PUT the full object.
+
+    Lexware's PUT replaces the whole contact and requires the current
+    ``version`` (optimistic locking). We therefore always fetch the live
+    contact first, merge the caller's ``changes`` onto it, and force the
+    just-fetched version — so the caller only ever supplies the fields that
+    change and can never break the version handshake.
+    """
+    current = client.get(f"/v1/contacts/{contact_id}")
+    merged = _merge_for_update(current, changes)
+    _guard_single_contact_person(merged)
+    return _put_and_return_object(client, f"/v1/contacts/{contact_id}", merged)
+
+
+def _guard_single_contact_person(contact: dict[str, Any]) -> None:
+    """Fail early on contacts the Lexware REST API refuses to update.
+
+    A company contact may hold multiple contact persons in the Lexware web
+    app, but the REST API accepts **at most one** on create/update — a PUT with
+    more returns an opaque HTTP 406 (`invalid_value` on `contactPersons.size`).
+    Since our update always PUTs the full object, such a contact can't be
+    edited via the API at all, even for an unrelated field. Turn that into a
+    clear, actionable message instead of a raw 406.
+    """
+    persons = (contact.get("company") or {}).get("contactPersons") or []
+    if len(persons) > 1:
+        raise LexwareError(
+            "Dieser Kontakt hat mehrere Ansprechpartner. Die Lexware-API erlaubt "
+            "pro Firmen-Kontakt nur einen, deshalb lassen sich solche Kontakte "
+            "nicht über die API bearbeiten (auch nicht für andere Felder). Bitte "
+            "die Änderung direkt in der Lexware-Weboberfläche vornehmen. Für "
+            "weitere Ansprechpartner empfiehlt sich ein eigener Kontakt."
+        )
+
+
 # -- Articles ---------------------------------------------------------------
 
 
@@ -600,3 +895,55 @@ def get_article(client: LexwareClient, article_id: str) -> dict[str, Any]:
 
 def create_article(client: LexwareClient, body: dict[str, Any]) -> dict[str, Any]:
     return client.post("/v1/articles", body)
+
+
+def update_article(
+    client: LexwareClient, article_id: str, changes: dict[str, Any]
+) -> dict[str, Any]:
+    """Partially update an article — same fetch/deep-merge/PUT flow as
+    :func:`update_contact` (articles also use ``version`` locking)."""
+    current = client.get(f"/v1/articles/{article_id}")
+    merged = _merge_for_update(current, changes)
+    return _put_and_return_object(client, f"/v1/articles/{article_id}", merged)
+
+
+def _merge_for_update(current: dict[str, Any], changes: dict[str, Any]) -> dict[str, Any]:
+    """Deep-merge ``changes`` onto a freshly fetched resource for a PUT.
+
+    Nested objects merge key-by-key; lists and scalars are replaced wholesale
+    (a list can't be meaningfully half-merged — pass the full list to change
+    one entry). The resource's own ``version`` always wins, so a caller who
+    echoes a stale version in ``changes`` can't trigger a false 409.
+    """
+    merged = _deep_merge(current, changes)
+    if "version" in current:
+        merged["version"] = current["version"]
+    return merged
+
+
+def _put_and_return_object(
+    client: LexwareClient, path: str, body: dict[str, Any]
+) -> dict[str, Any]:
+    """PUT ``body`` and return the full updated object, not Lexware's envelope.
+
+    Lexware's PUT responds with only a confirmation ({id, resourceUri, version,
+    createdDate, updatedDate}). The full object we just stored is far more
+    useful to the caller, so we return ``body`` with the new version stamped
+    in — no extra GET needed.
+    """
+    result = client.put(path, body)
+    updated = dict(body)
+    if isinstance(result, dict):
+        for key in ("version", "updatedDate", "id", "resourceUri"):
+            if key in result:
+                updated[key] = result[key]
+    return updated
+
+
+def _deep_merge(base: Any, changes: Any) -> Any:
+    if isinstance(base, dict) and isinstance(changes, dict):
+        out = dict(base)
+        for key, value in changes.items():
+            out[key] = _deep_merge(base[key], value) if key in base else value
+        return out
+    return changes

lxw_cli-0.4.0/src/lxw_cli/feature_request.py

@@ -0,0 +1,57 @@
+"""Compose a non-binding feature request for the user to send to the vendor.
+
+This is an **end-customer product**: the assistant must not offer to build or
+extend the software itself. When a user wants functionality the tools don't
+cover, the ``request_feature`` MCP tool returns a ready-to-send message (subject
++ body) and the vendor's address (oemedia) — the user copies it and sends the
+email themselves. The server does **not** send any mail. No promise is made
+about whether or when the feature is built.
+"""
+
+from __future__ import annotations
+
+DEFAULT_TO = "david@oemedia.de"
+SUBJECT = "Lexware-MCP — Funktionsanfrage (unverbindlich)"
+
+
+class FeatureRequestError(Exception):
+    """Raised when a feature request cannot be composed."""
+
+
+def compose_feature_request(
+    *,
+    description: str,
+    company: str | None = None,
+    contact_email: str | None = None,
+) -> dict[str, str]:
+    """Build a copy-paste-ready feature request. Sends nothing.
+
+    Returns ``{to, subject, body, hinweis}``. Raises
+    :class:`FeatureRequestError` on empty input.
+    """
+    text = (description or "").strip()
+    if not text:
+        raise FeatureRequestError("Bitte den gewünschten Funktionswunsch beschreiben.")
+
+    subject = SUBJECT + (f" — {company}" if company else "")
+    lines = [
+        "Unverbindliche Funktionsanfrage zum Lexware-MCP-Tool.",
+        "",
+        f"Kunde:        {company or '(bitte ergänzen)'}",
+        f"Kontakt-Mail: {contact_email or '(bitte ergänzen)'}",
+        "",
+        "Wunsch:",
+        text,
+        "",
+        "Hinweis: unverbindlich, keine Zusage zur Umsetzung.",
+    ]
+    return {
+        "to": DEFAULT_TO,
+        "subject": subject,
+        "body": "\n".join(lines),
+        "hinweis": (
+            "Dies ist ein unverbindlicher Funktionswunsch. Bitte den obigen Text "
+            f"per E-Mail an {DEFAULT_TO} senden — der Server verschickt nichts "
+            "selbst."
+        ),
+    }