Metadata-Version: 2.4
Name: xta-tool
Version: 0.7.0
Summary: A command line tool for sending and receiving XÖV Transport Adapter (XTA) messages.
Keywords: MTOM-XOP,XTA
Author: Jan Zickermann
Author-email: Jan Zickermann <janz@noreply.codeberg.org>
License-Expression: AGPL-3.0-or-later
License-File: LICENSES/AGPL-3.0-or-later.txt
License-File: LICENSES/CC0-1.0.txt
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Dist: click>=8.3.1
Requires-Dist: httpx[socks]>=0.28.1
Requires-Dist: jinja2>=3.1.6
Requires-Dist: pydantic==2.12.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: tqdm>=4.67.3
Requires-Dist: xdg-base-dirs>=6.0.2
Requires-Python: >=3.12
Project-URL: Issue Tracker, https://codeberg.org/janz/xta-tool/issues
Project-URL: Repository, https://codeberg.org/janz/xta-tool
Description-Content-Type: text/markdown

<!--
SPDX-FileCopyrightText: 2026 Jan Zickermann <janz@noreply.codeberg.org>

SPDX-License-Identifier: AGPL-3.0-or-later
-->

# xta-tool

A command line tool for sending and receiving [XÖV Transport Adapter (XTA)](https://www.xrepository.de/details/urn:xoev-de:kosit:standard:xta2_3.1.1#version) messages.

[![PyPI - Version](https://img.shields.io/pypi/v/xta-tool)](https://pypi.org/project/xta-tool/)

## Usage

```
Usage: xta [OPTIONS] COMMAND [ARGS]...

  Send and receive xta messages.

Options:
  -c, --config PATH   Use an extra configuration directory or file.
  -p, --profile TEXT  Use comma-separated configuration profiles.
  --version           Show the version and exit.
  --help              Show this message and exit.

Commands:
  close        Close a message by its ID, acknowledging it has been read.
  get          Get a message by ID and save it to PATH.
  inspect      Inspect a message by ID, showing its transport report.
  ls           List open messages by id.
  new          Get a new message id from the server.
  send         Send a message with ID from PATH.
  show-config  Show the active configuration values.
```

## Config

The tool loads configuration values from `$XDG_CONFIG_HOME/xta/config.toml` and uses these values as defaults:

```toml
# Base URL for all three XTA service ports
base-url: str = "https://localhost:8443"
# Path to ManagementPort
management-port-path = "/services/XTAService/ManagementPort"
# Path to MsgBoxPort
msg-box-port-path = "/services/XTAService/MsgBoxPort"
# Path to SendXtaPort
send-port-path = "/services/XTAService/SendXtaPort"
# Enable verification of XTA server certificate
verify = true
# Root CA certificate, or empty to use system defaults (where path is relative to any config directory)
cafile = "ca.crt"
# Client certificate, or empty to use none (where path is relative to any config directory)
certfile = "tls.crt"
# Private key of client certificate, or empty to use none (where path is relative to any config directory)
keyfile = "tls.key"
# User-Agent in HTTP header, or empty to use none
user-agent = "Apache-CXF/4.0.7"
# Host in HTTP header, or empty to use default
host = ""
# Print response HTTP headers and SOAP envelope to stderr
verbose = false
# Limit size of file download when encoding to base64 (default 1 MiB)
max-save-base64-size = 1048576
# Limit size of response envelope (default 10 MiB)
max-response-envelope-size = 10485760
# Max entries when listing open messages
max-list-items = 100

# XTA PartyIdentifier used to identify this client
[self-identifier]
# Type
typ = "xoev"
# Category, or empty to use none
category = ""
# Name, or empty to use none
name = ""
# Certified identifier (for instance: "praefix:behoerdenschluessel"), or Wildcard identifier "*"
value = "*"
```

Configuration values may be overridden by profile configuration files. For instance, if `XTA_TOOL_CONFIG=path/to/config.toml XTA_TOOL_PROFILE=profile1,profile2,profile3` is set, it reads values from `path/to/config.toml` and then from `path/to/config-profile{1,2,3}.toml`.

## Send Message

Upload a message to the XTA server by:
```shell script
xta send new xta-message.yaml
```
where `xta-message.yaml` contains, for instance:
```yaml
metadata:
  service: "urn:fim:Wohngeld-Mietzuschuss:1.5"
  businessScenario:
    code: "FIM-WOHNGELD_DATA"
    listUri: "urn:de:xta:codeliste:business.scenario"
    listVersionId: "3.6"
  messageType:
    code: "fim.S05000227.05000227001005"
  messageTypePayloadSchema: "urn:xoev-de:xfall:standard:fim-s05000227_1.5"
  author:
    category: "Wohngeldportal"
    value: "wgp:010500100000"
  reader:
    category: "Wohngeldbehörde"
    value: "wgb:051110000000"

message:
  fileName: main.xml
  content: ./path/to/main.xml
  contentType: application/xml
attachments:
  - fileName: extra.txt
    content: ./path/to/extra.txt
    contentType: plain/txt
```

If a content path points to a directory, the tool sends all files in the directory as a ZIP archive.

If a content file path ends in `.jinja`, the tool sends the file after rendering it as a [jinja2 template](https://jinja.palletsprojects.com/en/stable/templates/) with `config`, `metdata`, `message` and `attachments` in the templating context.

## Get Message

Download a message by its ID from the XTA server by:
```shell script
xta get urn:some:message:id path/to/message
```
If `path/to/message` is an existing directory, the tool downloads attached files into the directory and references them in a message yaml `path/to/message/xta-message.yaml`, for instance, with `content: main.xml`.

If the output path is not an existing directory, the tool writes attached files directly as Base64 strings, meaning `content: base64:...`, into the message yaml `path/to/message`.

## Install

Install `xta` as a command line tool by

```shell script
uv tool install .
```

# References
- [XÖV Transport Adapter (XTA)](https://www.xrepository.de/details/urn:xoev-de:kosit:standard:xta2_3.1.1#version)
- Sources for XTA requests and responses:
  - Examples generated with [WSDL files for the conformity test by KoSIT](https://projekte.kosit.org/transport-public/XTA2V3-KonTest/-/tree/1c271ddd39c90c752e205f68989cc95f30299302/src/main/resources/wsdl) using Apache CXF.
  - [Content-Type `multipart/related`](https://www.rfc-editor.org/rfc/rfc2387) for [SOAP attachments](https://www.w3.org/TR/SOAP-attachments/) with [MTOM-XOP](https://www.w3.org/TR/soap12-mtom/).
- Example from [Wohngeld-FIM 4.1 XTA-Transportauftrag](https://docs.fitko.de/dvdv/assets/files/DVDV-Eintragungskonzept_FIM-Wohngeld_Version1.5-1f4d910cfe503a84bbccc673b5acc9d7.pdf)
