Metadata-Version: 2.4
Name: xta-tool
Version: 0.2.0
Summary: A command line tool for sending and receiving XÖV Transport Adapter (XTA) messages.
Keywords: XTA,MTOM-XOP
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: License :: OSI Approved
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
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 :: Software Development
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Utilities
Requires-Dist: click>=8.3.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: jinja2>=3.1.6
Requires-Dist: pydantic==2.12.0
Requires-Dist: pyyaml>=6.0.3
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 FILE   Use a custom configuration file location.  [default:
                      /var/home/jan/.xta/config.toml]
  -p, --profile TEXT  Use a configuration profile.
  --version           Show the version and exit.
  --help              Show this message and exit.

Commands:
  close    Close a message by its ID, acknowledging that it has been read.
  config   Show active configuration values.
  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.
```

## Config

The tool loads configuration values from `~/.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 (leave empty to use system defaults)
cafile = "~/.xta/ca.crt"
# Client certificate (leave empty to use none)
certfile = "~/.xta/tls.crt"
# Private key of client certificate
keyfile = "~/.xta/tls.key"
# User-Agent in HTTP header
user-agent = "Apache-CXF/4.0.7"
# 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
category = ""
# Name
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:some:ServiceName"
  businessScenario:
    code: "XMELD"
    listUri: "urn:de:dataport:codeliste:business.scenario"
    listVersionId: "1.0"
  messageType:
    code: "SomeMessageTypeCode"
  messageTypePayloadSchema: "urn:some:MessageTypePayloadSchema"
  author:
    value: praefix:author-behoerdenschluessel
  reader:
    value: praefix:reader-behoerdenschluessel

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/).
