post-at-lib 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- post_at_lib-0.1.0/.gitignore +14 -0
- post_at_lib-0.1.0/CHANGELOG.md +44 -0
- post_at_lib-0.1.0/LICENSE +21 -0
- post_at_lib-0.1.0/PKG-INFO +219 -0
- post_at_lib-0.1.0/README.md +189 -0
- post_at_lib-0.1.0/pyproject.toml +59 -0
- post_at_lib-0.1.0/scripts/capture.py +112 -0
- post_at_lib-0.1.0/src/post_at/__init__.py +26 -0
- post_at_lib-0.1.0/src/post_at/auth.py +292 -0
- post_at_lib-0.1.0/src/post_at/client.py +617 -0
- post_at_lib-0.1.0/src/post_at/errors.py +41 -0
- post_at_lib-0.1.0/src/post_at/graphql/AddShipmentInbound.graphql +1 -0
- post_at_lib-0.1.0/src/post_at/graphql/AddShipmentOutbound.graphql +1 -0
- post_at_lib-0.1.0/src/post_at/graphql/BoundingBox.graphql +1 -0
- post_at_lib-0.1.0/src/post_at/graphql/PossibleRedirections.graphql +1 -0
- post_at_lib-0.1.0/src/post_at/graphql/RedirectShipmentNeighbor.graphql +1 -0
- post_at_lib-0.1.0/src/post_at/graphql/RedirectShipmentParcelLocker.graphql +1 -0
- post_at_lib-0.1.0/src/post_at/graphql/RedirectShipmentPlace.graphql +1 -0
- post_at_lib-0.1.0/src/post_at/graphql/RedirectShipmentPostOffice.graphql +1 -0
- post_at_lib-0.1.0/src/post_at/graphql/RemoveShipmentInbound.graphql +1 -0
- post_at_lib-0.1.0/src/post_at/graphql/RemoveShipmentOutbound.graphql +1 -0
- post_at_lib-0.1.0/src/post_at/graphql/RenameShipment.graphql +1 -0
- post_at_lib-0.1.0/src/post_at/graphql/ResetNeighborShipmentRedirection.graphql +1 -0
- post_at_lib-0.1.0/src/post_at/graphql/ResetParcelLockerShipmentRedirection.graphql +1 -0
- post_at_lib-0.1.0/src/post_at/graphql/ResetPlaceShipmentRedirection.graphql +1 -0
- post_at_lib-0.1.0/src/post_at/graphql/ResetPostOfficeShipmentRedirection.graphql +1 -0
- post_at_lib-0.1.0/src/post_at/graphql/ShipmentAuth.graphql +1 -0
- post_at_lib-0.1.0/src/post_at/graphql/ShipmentList.graphql +1 -0
- post_at_lib-0.1.0/src/post_at/graphql/ShipmentPublic.graphql +1 -0
- post_at_lib-0.1.0/src/post_at/models.py +619 -0
- post_at_lib-0.1.0/src/post_at/py.typed +0 -0
- post_at_lib-0.1.0/tests/fixtures/last_parcel_stamp_shipper_address.json +12 -0
- post_at_lib-0.1.0/tests/fixtures/marketing_preferences.json +111 -0
- post_at_lib-0.1.0/tests/fixtures/order_details.json +87 -0
- post_at_lib-0.1.0/tests/fixtures/order_history.json +26 -0
- post_at_lib-0.1.0/tests/fixtures/possible_redirections.json +114 -0
- post_at_lib-0.1.0/tests/fixtures/push_settings.json +89 -0
- post_at_lib-0.1.0/tests/fixtures/receiving_options.json +21 -0
- post_at_lib-0.1.0/tests/fixtures/shipment.json +159 -0
- post_at_lib-0.1.0/tests/fixtures/shipments.json +348 -0
- post_at_lib-0.1.0/tests/fixtures/track.json +123 -0
- post_at_lib-0.1.0/tests/fixtures/user.json +43 -0
- post_at_lib-0.1.0/tests/test_client.py +203 -0
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
.venv/
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.egg-info/
|
|
4
|
+
.pytest_cache/
|
|
5
|
+
dist/
|
|
6
|
+
build/
|
|
7
|
+
# login state (refresh token) and personal API dumps
|
|
8
|
+
.post_session.json
|
|
9
|
+
captures/
|
|
10
|
+
# decompiled app and APKs
|
|
11
|
+
research/
|
|
12
|
+
*.apkm
|
|
13
|
+
# source artwork; derived logo lives in assets/
|
|
14
|
+
Post-Logo-RGB-Farbe.png
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
## [0.1.0] - 2026-11-19
|
|
11
|
+
|
|
12
|
+
Initial release.
|
|
13
|
+
|
|
14
|
+
### Added
|
|
15
|
+
|
|
16
|
+
- `PostAtClient`: synchronous `httpx` client for the backend-for-frontend API
|
|
17
|
+
(`https://api.post.at/bff/`) used by the Österreichische Post Android app 2.16.0.
|
|
18
|
+
- Login via Azure AD B2C (`login.post.at`) without a browser (`login()`), and a
|
|
19
|
+
browser-based PKCE flow (`begin_browser_login()` / `complete_browser_login()`)
|
|
20
|
+
for accounts that need MFA or have to accept new terms.
|
|
21
|
+
- Session persistence in a JSON file that keeps the rotating refresh token;
|
|
22
|
+
access tokens for every scope are minted and refreshed on demand, and a 401
|
|
23
|
+
triggers one refresh and a retry.
|
|
24
|
+
- Public endpoints without login: parcel tracking, branch/parcel locker search,
|
|
25
|
+
service filters, places, app config, strings, master data, address validation.
|
|
26
|
+
- Shipments (GraphQL): list sent and received parcels, single shipment, add,
|
|
27
|
+
remove and rename shipments.
|
|
28
|
+
- Redirections: query possible redirections; redirect to a neighbour, parcel
|
|
29
|
+
locker, post office or place; reset redirections.
|
|
30
|
+
- User profile, addresses, receiving options, marketing preferences, push
|
|
31
|
+
settings and push devices/notifications.
|
|
32
|
+
- Order history, order details and attachments, collection service, parcel
|
|
33
|
+
stamps, shop/checkout and identification (Jumio, ID Austria) endpoints.
|
|
34
|
+
- Pydantic models (`post_at.models`) with English snake_case fields for all
|
|
35
|
+
responses verified against a real account; unknown fields are preserved and
|
|
36
|
+
unknown enum values fall back to plain strings.
|
|
37
|
+
- Error hierarchy: `PostAtError`, `ApiError`, `GraphQLError`,
|
|
38
|
+
`AuthenticationError`, `NotAuthenticatedError`, `InteractionRequiredError`.
|
|
39
|
+
- `scripts/capture.py` to re-capture read-only API responses (redacted by
|
|
40
|
+
default) after app or API changes.
|
|
41
|
+
- PEP 561 `py.typed` marker.
|
|
42
|
+
|
|
43
|
+
[Unreleased]: https://github.com/ch-rit/post_at_lib/compare/v0.1.0...HEAD
|
|
44
|
+
[0.1.0]: https://github.com/ch-rit/post_at_lib/releases/tag/v0.1.0
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Christoph Ritzer
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: post-at-lib
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Unofficial client for the Österreichische Post (post.at) app API
|
|
5
|
+
Project-URL: Homepage, https://github.com/ch-rit/post_at_lib
|
|
6
|
+
Project-URL: Source, https://github.com/ch-rit/post_at_lib
|
|
7
|
+
Project-URL: Issues, https://github.com/ch-rit/post_at_lib/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/ch-rit/post_at_lib/blob/main/CHANGELOG.md
|
|
9
|
+
Author-email: Christoph Ritzer <c.ritzer@gmx.at>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: api-client,austrian post,parcel,post.at,shipment,tracking,österreichische post
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
22
|
+
Classifier: Topic :: Home Automation
|
|
23
|
+
Classifier: Typing :: Typed
|
|
24
|
+
Requires-Python: >=3.11
|
|
25
|
+
Requires-Dist: httpx>=0.27
|
|
26
|
+
Requires-Dist: pydantic>=2.11
|
|
27
|
+
Provides-Extra: test
|
|
28
|
+
Requires-Dist: pytest; extra == 'test'
|
|
29
|
+
Description-Content-Type: text/markdown
|
|
30
|
+
|
|
31
|
+
<p align="center">
|
|
32
|
+
<img src="https://github.com/ch-rit/post_at_lib/blob/main/assets/logo.png?raw=true" alt="post-at-lib logo" width="360">
|
|
33
|
+
</p>
|
|
34
|
+
|
|
35
|
+
# post-at-lib
|
|
36
|
+
|
|
37
|
+
[](https://pypi.org/project/post-at-lib/)
|
|
38
|
+
[](https://pypi.org/project/post-at-lib/)
|
|
39
|
+
[](https://github.com/ch-rit/post_at_lib/blob/main/LICENSE)
|
|
40
|
+
[](https://github.com/ch-rit/post_at_lib/actions/workflows/tests.yaml)
|
|
41
|
+
|
|
42
|
+
Unofficial Python client for the API behind the Österreichische Post app
|
|
43
|
+
(`at.post.app` 2.16.0). Endpoints, headers and API versions were taken from the
|
|
44
|
+
decompiled app; the library talks to `https://api.post.at/bff/` directly. No
|
|
45
|
+
request signing, app attestation or certificate pinning is involved.
|
|
46
|
+
|
|
47
|
+
> [!WARNING]
|
|
48
|
+
> **Unofficial project, use at your own risk.**
|
|
49
|
+
>
|
|
50
|
+
> - This library is **not affiliated with, endorsed by or supported by
|
|
51
|
+
> Österreichische Post AG**. "Post", "post.at" and the post horn logo are
|
|
52
|
+
> their trademarks; the logo above is a modified version used only to
|
|
53
|
+
> identify the service this library talks to.
|
|
54
|
+
> - It uses an undocumented, private API that can change or break at any time.
|
|
55
|
+
> - The code is **fully vibecoded**: it was written by an AI and only lightly
|
|
56
|
+
> reviewed by a human.
|
|
57
|
+
> - It comes with **no guarantee and no warranty** of any kind (see the
|
|
58
|
+
> [MIT license](https://github.com/ch-rit/post_at_lib/blob/main/LICENSE)).
|
|
59
|
+
> You are responsible for what it does with your account.
|
|
60
|
+
|
|
61
|
+
Looking for Home Assistant? The companion integration
|
|
62
|
+
[ha-post-at](https://github.com/ch-rit/ha-post-at) is built on this library.
|
|
63
|
+
|
|
64
|
+
## Features
|
|
65
|
+
|
|
66
|
+
- Track any parcel by tracking number, no login needed.
|
|
67
|
+
- Log in with e-mail and password (no browser), or through a browser when the
|
|
68
|
+
account needs MFA; the rotating refresh token is persisted in a session file.
|
|
69
|
+
- List all sent and received parcels of your account, add, remove and rename them.
|
|
70
|
+
- Query and set delivery redirections (neighbour, parcel locker, post office, place).
|
|
71
|
+
- Search branches and parcel lockers in a map area.
|
|
72
|
+
- Read and update the user profile, addresses, receiving options, push and
|
|
73
|
+
marketing settings; read order history, collection services and parcel stamps.
|
|
74
|
+
- Typed pydantic models with English field names, `py.typed` included.
|
|
75
|
+
|
|
76
|
+
## Installation
|
|
77
|
+
|
|
78
|
+
Requires Python 3.11+.
|
|
79
|
+
|
|
80
|
+
```sh
|
|
81
|
+
pip install post-at-lib
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
The distribution is called `post-at-lib`; the import name is `post_at`.
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
import post_at
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## Usage
|
|
91
|
+
|
|
92
|
+
```python
|
|
93
|
+
from post_at import PostAtClient
|
|
94
|
+
|
|
95
|
+
with PostAtClient(session_file=".post_session.json") as post:
|
|
96
|
+
# public, no login
|
|
97
|
+
parcel = post.track("1012345678901234567890")
|
|
98
|
+
print(parcel.latest_event.state, parcel.estimated_delivery_date_text)
|
|
99
|
+
post.branches(north_west=(48.25, 16.30), south_east=(48.18, 16.42), branch_types=["FILIALE"])
|
|
100
|
+
|
|
101
|
+
# login once; the session file keeps the rotating refresh token
|
|
102
|
+
if not post.logged_in:
|
|
103
|
+
post.login("me@example.com", "secret")
|
|
104
|
+
|
|
105
|
+
for shipment in post.shipments().shipments: # all sent and received parcels
|
|
106
|
+
print(shipment.tracking_number, shipment.sender, shipment.latest_event.state_key)
|
|
107
|
+
|
|
108
|
+
options = post.possible_redirections("1012345678901234567890").options
|
|
109
|
+
if any(o.type == "PLACE" and o.state == "ENABLED" for o in options):
|
|
110
|
+
post.redirect_to_place("1012345678901234567890", post.places()[0])
|
|
111
|
+
|
|
112
|
+
user = post.user()
|
|
113
|
+
user.mobile.number = "1234567"
|
|
114
|
+
post.update_user(user)
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
The session file contains a refresh token for your account. Keep it private.
|
|
118
|
+
|
|
119
|
+
### Login
|
|
120
|
+
|
|
121
|
+
`login()` replays the Azure AD B2C sign-in page (`login.post.at`, policy
|
|
122
|
+
`B2C_1A_signup_signin_mobileapp`) without a browser. If B2C asks for anything
|
|
123
|
+
other than e-mail and password (MFA, new terms), it raises
|
|
124
|
+
`InteractionRequiredError`; use the browser flow instead:
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
pending = post.begin_browser_login()
|
|
128
|
+
print(pending.url) # open it and sign in
|
|
129
|
+
# The browser cannot open the final msal228c4360-…://at.post.app/auth?code=… URL.
|
|
130
|
+
# Copy it from the address bar, the error page or the devtools network tab.
|
|
131
|
+
post.complete_browser_login(pending, input("redirect URL: "))
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### Tokens
|
|
135
|
+
|
|
136
|
+
The BFF needs up to two bearer tokens per request, minted from the same refresh token:
|
|
137
|
+
|
|
138
|
+
| Endpoint group | `Authorization` | `X-Authorization` |
|
|
139
|
+
|---|---|---|
|
|
140
|
+
| shipments (GraphQL), orders, push, marketing | `PostApp2.AllAccess` | – |
|
|
141
|
+
| user profile, addresses, receiving options | `PostApp2.AllAccess` | `KIAM.Service.UserContext.All` |
|
|
142
|
+
| identification (Jumio, ID Austria) | `PostApp2.AllAccess` | `Kiam.Identifications.IdAustria.Create` |
|
|
143
|
+
|
|
144
|
+
The client fetches and refreshes tokens on demand. A 401 forces one refresh and a retry.
|
|
145
|
+
|
|
146
|
+
### Errors
|
|
147
|
+
|
|
148
|
+
All exceptions derive from `PostAtError`.
|
|
149
|
+
|
|
150
|
+
- `ApiError`: non-2xx answer, with `status_code`, decoded `body` and the server's `operation_id`.
|
|
151
|
+
- `GraphQLError`: GraphQL `errors` array.
|
|
152
|
+
- `AuthenticationError` / `NotAuthenticatedError` / `InteractionRequiredError`: login and token problems.
|
|
153
|
+
|
|
154
|
+
### Models
|
|
155
|
+
|
|
156
|
+
Endpoints whose responses were verified against a real account return pydantic
|
|
157
|
+
models (`post_at.models`): shipments, tracking events, redirection options,
|
|
158
|
+
branches, user, addresses, receiving options, orders, push and marketing
|
|
159
|
+
settings. Field names are English snake_case. `model_dump()` gives back the
|
|
160
|
+
original JSON keys, and fields the server adds later stay in `model_extra`. Enum
|
|
161
|
+
fields fall back to the plain string for values they don't know.
|
|
162
|
+
|
|
163
|
+
The shop/checkout, push-device and identification endpoints return decoded JSON
|
|
164
|
+
as-is. Their responses haven't been seen yet.
|
|
165
|
+
|
|
166
|
+
The GraphQL documents the app sends are in
|
|
167
|
+
[`src/post_at/graphql/`](https://github.com/ch-rit/post_at_lib/tree/main/src/post_at/graphql).
|
|
168
|
+
|
|
169
|
+
### Re-capturing after app/API changes
|
|
170
|
+
|
|
171
|
+
`scripts/capture.py` logs in (or reuses `.post_session.json`), calls every
|
|
172
|
+
read-only endpoint and writes the responses to `captures/`. Personal data is
|
|
173
|
+
masked unless you pass `--no-redact`. `tests/fixtures/` holds sanitized copies
|
|
174
|
+
of such captures, and the tests replay them.
|
|
175
|
+
|
|
176
|
+
```sh
|
|
177
|
+
.venv/bin/python scripts/capture.py # e-mail/password prompt
|
|
178
|
+
.venv/bin/python scripts/capture.py --browser # sign in in a browser, paste the redirect URL
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
## Development
|
|
182
|
+
|
|
183
|
+
```sh
|
|
184
|
+
git clone https://github.com/ch-rit/post_at_lib.git
|
|
185
|
+
cd post_at_lib
|
|
186
|
+
python -m venv .venv
|
|
187
|
+
.venv/bin/pip install -e '.[test]'
|
|
188
|
+
.venv/bin/pytest
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
The tests replay the fixtures in `tests/fixtures/` and make no network requests.
|
|
192
|
+
|
|
193
|
+
## Releasing
|
|
194
|
+
|
|
195
|
+
1. Bump `version` in `pyproject.toml` and move the `Unreleased` entries in
|
|
196
|
+
[`CHANGELOG.md`](https://github.com/ch-rit/post_at_lib/blob/main/CHANGELOG.md)
|
|
197
|
+
to a new version section.
|
|
198
|
+
2. Commit, then tag and push:
|
|
199
|
+
|
|
200
|
+
```sh
|
|
201
|
+
git tag v0.1.0
|
|
202
|
+
git push origin main v0.1.0
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
3. The `Release` workflow checks that the tag matches the version in
|
|
206
|
+
`pyproject.toml`, builds sdist and wheel, publishes them to PyPI via trusted
|
|
207
|
+
publishing and creates a GitHub release with the files attached.
|
|
208
|
+
|
|
209
|
+
One-time setup:
|
|
210
|
+
|
|
211
|
+
- On [pypi.org](https://pypi.org/manage/account/publishing/) add a *pending
|
|
212
|
+
trusted publisher* for project `post-at-lib`: owner `ch-rit`, repository
|
|
213
|
+
`post_at_lib`, workflow `release.yaml`, environment `pypi`.
|
|
214
|
+
- In the GitHub repository settings, create an environment named `pypi`
|
|
215
|
+
(optionally with required reviewers or a `v*` tag rule).
|
|
216
|
+
|
|
217
|
+
## License
|
|
218
|
+
|
|
219
|
+
[MIT](https://github.com/ch-rit/post_at_lib/blob/main/LICENSE) © 2026 Christoph Ritzer
|
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://github.com/ch-rit/post_at_lib/blob/main/assets/logo.png?raw=true" alt="post-at-lib logo" width="360">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
# post-at-lib
|
|
6
|
+
|
|
7
|
+
[](https://pypi.org/project/post-at-lib/)
|
|
8
|
+
[](https://pypi.org/project/post-at-lib/)
|
|
9
|
+
[](https://github.com/ch-rit/post_at_lib/blob/main/LICENSE)
|
|
10
|
+
[](https://github.com/ch-rit/post_at_lib/actions/workflows/tests.yaml)
|
|
11
|
+
|
|
12
|
+
Unofficial Python client for the API behind the Österreichische Post app
|
|
13
|
+
(`at.post.app` 2.16.0). Endpoints, headers and API versions were taken from the
|
|
14
|
+
decompiled app; the library talks to `https://api.post.at/bff/` directly. No
|
|
15
|
+
request signing, app attestation or certificate pinning is involved.
|
|
16
|
+
|
|
17
|
+
> [!WARNING]
|
|
18
|
+
> **Unofficial project, use at your own risk.**
|
|
19
|
+
>
|
|
20
|
+
> - This library is **not affiliated with, endorsed by or supported by
|
|
21
|
+
> Österreichische Post AG**. "Post", "post.at" and the post horn logo are
|
|
22
|
+
> their trademarks; the logo above is a modified version used only to
|
|
23
|
+
> identify the service this library talks to.
|
|
24
|
+
> - It uses an undocumented, private API that can change or break at any time.
|
|
25
|
+
> - The code is **fully vibecoded**: it was written by an AI and only lightly
|
|
26
|
+
> reviewed by a human.
|
|
27
|
+
> - It comes with **no guarantee and no warranty** of any kind (see the
|
|
28
|
+
> [MIT license](https://github.com/ch-rit/post_at_lib/blob/main/LICENSE)).
|
|
29
|
+
> You are responsible for what it does with your account.
|
|
30
|
+
|
|
31
|
+
Looking for Home Assistant? The companion integration
|
|
32
|
+
[ha-post-at](https://github.com/ch-rit/ha-post-at) is built on this library.
|
|
33
|
+
|
|
34
|
+
## Features
|
|
35
|
+
|
|
36
|
+
- Track any parcel by tracking number, no login needed.
|
|
37
|
+
- Log in with e-mail and password (no browser), or through a browser when the
|
|
38
|
+
account needs MFA; the rotating refresh token is persisted in a session file.
|
|
39
|
+
- List all sent and received parcels of your account, add, remove and rename them.
|
|
40
|
+
- Query and set delivery redirections (neighbour, parcel locker, post office, place).
|
|
41
|
+
- Search branches and parcel lockers in a map area.
|
|
42
|
+
- Read and update the user profile, addresses, receiving options, push and
|
|
43
|
+
marketing settings; read order history, collection services and parcel stamps.
|
|
44
|
+
- Typed pydantic models with English field names, `py.typed` included.
|
|
45
|
+
|
|
46
|
+
## Installation
|
|
47
|
+
|
|
48
|
+
Requires Python 3.11+.
|
|
49
|
+
|
|
50
|
+
```sh
|
|
51
|
+
pip install post-at-lib
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
The distribution is called `post-at-lib`; the import name is `post_at`.
|
|
55
|
+
|
|
56
|
+
```python
|
|
57
|
+
import post_at
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Usage
|
|
61
|
+
|
|
62
|
+
```python
|
|
63
|
+
from post_at import PostAtClient
|
|
64
|
+
|
|
65
|
+
with PostAtClient(session_file=".post_session.json") as post:
|
|
66
|
+
# public, no login
|
|
67
|
+
parcel = post.track("1012345678901234567890")
|
|
68
|
+
print(parcel.latest_event.state, parcel.estimated_delivery_date_text)
|
|
69
|
+
post.branches(north_west=(48.25, 16.30), south_east=(48.18, 16.42), branch_types=["FILIALE"])
|
|
70
|
+
|
|
71
|
+
# login once; the session file keeps the rotating refresh token
|
|
72
|
+
if not post.logged_in:
|
|
73
|
+
post.login("me@example.com", "secret")
|
|
74
|
+
|
|
75
|
+
for shipment in post.shipments().shipments: # all sent and received parcels
|
|
76
|
+
print(shipment.tracking_number, shipment.sender, shipment.latest_event.state_key)
|
|
77
|
+
|
|
78
|
+
options = post.possible_redirections("1012345678901234567890").options
|
|
79
|
+
if any(o.type == "PLACE" and o.state == "ENABLED" for o in options):
|
|
80
|
+
post.redirect_to_place("1012345678901234567890", post.places()[0])
|
|
81
|
+
|
|
82
|
+
user = post.user()
|
|
83
|
+
user.mobile.number = "1234567"
|
|
84
|
+
post.update_user(user)
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
The session file contains a refresh token for your account. Keep it private.
|
|
88
|
+
|
|
89
|
+
### Login
|
|
90
|
+
|
|
91
|
+
`login()` replays the Azure AD B2C sign-in page (`login.post.at`, policy
|
|
92
|
+
`B2C_1A_signup_signin_mobileapp`) without a browser. If B2C asks for anything
|
|
93
|
+
other than e-mail and password (MFA, new terms), it raises
|
|
94
|
+
`InteractionRequiredError`; use the browser flow instead:
|
|
95
|
+
|
|
96
|
+
```python
|
|
97
|
+
pending = post.begin_browser_login()
|
|
98
|
+
print(pending.url) # open it and sign in
|
|
99
|
+
# The browser cannot open the final msal228c4360-…://at.post.app/auth?code=… URL.
|
|
100
|
+
# Copy it from the address bar, the error page or the devtools network tab.
|
|
101
|
+
post.complete_browser_login(pending, input("redirect URL: "))
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### Tokens
|
|
105
|
+
|
|
106
|
+
The BFF needs up to two bearer tokens per request, minted from the same refresh token:
|
|
107
|
+
|
|
108
|
+
| Endpoint group | `Authorization` | `X-Authorization` |
|
|
109
|
+
|---|---|---|
|
|
110
|
+
| shipments (GraphQL), orders, push, marketing | `PostApp2.AllAccess` | – |
|
|
111
|
+
| user profile, addresses, receiving options | `PostApp2.AllAccess` | `KIAM.Service.UserContext.All` |
|
|
112
|
+
| identification (Jumio, ID Austria) | `PostApp2.AllAccess` | `Kiam.Identifications.IdAustria.Create` |
|
|
113
|
+
|
|
114
|
+
The client fetches and refreshes tokens on demand. A 401 forces one refresh and a retry.
|
|
115
|
+
|
|
116
|
+
### Errors
|
|
117
|
+
|
|
118
|
+
All exceptions derive from `PostAtError`.
|
|
119
|
+
|
|
120
|
+
- `ApiError`: non-2xx answer, with `status_code`, decoded `body` and the server's `operation_id`.
|
|
121
|
+
- `GraphQLError`: GraphQL `errors` array.
|
|
122
|
+
- `AuthenticationError` / `NotAuthenticatedError` / `InteractionRequiredError`: login and token problems.
|
|
123
|
+
|
|
124
|
+
### Models
|
|
125
|
+
|
|
126
|
+
Endpoints whose responses were verified against a real account return pydantic
|
|
127
|
+
models (`post_at.models`): shipments, tracking events, redirection options,
|
|
128
|
+
branches, user, addresses, receiving options, orders, push and marketing
|
|
129
|
+
settings. Field names are English snake_case. `model_dump()` gives back the
|
|
130
|
+
original JSON keys, and fields the server adds later stay in `model_extra`. Enum
|
|
131
|
+
fields fall back to the plain string for values they don't know.
|
|
132
|
+
|
|
133
|
+
The shop/checkout, push-device and identification endpoints return decoded JSON
|
|
134
|
+
as-is. Their responses haven't been seen yet.
|
|
135
|
+
|
|
136
|
+
The GraphQL documents the app sends are in
|
|
137
|
+
[`src/post_at/graphql/`](https://github.com/ch-rit/post_at_lib/tree/main/src/post_at/graphql).
|
|
138
|
+
|
|
139
|
+
### Re-capturing after app/API changes
|
|
140
|
+
|
|
141
|
+
`scripts/capture.py` logs in (or reuses `.post_session.json`), calls every
|
|
142
|
+
read-only endpoint and writes the responses to `captures/`. Personal data is
|
|
143
|
+
masked unless you pass `--no-redact`. `tests/fixtures/` holds sanitized copies
|
|
144
|
+
of such captures, and the tests replay them.
|
|
145
|
+
|
|
146
|
+
```sh
|
|
147
|
+
.venv/bin/python scripts/capture.py # e-mail/password prompt
|
|
148
|
+
.venv/bin/python scripts/capture.py --browser # sign in in a browser, paste the redirect URL
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Development
|
|
152
|
+
|
|
153
|
+
```sh
|
|
154
|
+
git clone https://github.com/ch-rit/post_at_lib.git
|
|
155
|
+
cd post_at_lib
|
|
156
|
+
python -m venv .venv
|
|
157
|
+
.venv/bin/pip install -e '.[test]'
|
|
158
|
+
.venv/bin/pytest
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
The tests replay the fixtures in `tests/fixtures/` and make no network requests.
|
|
162
|
+
|
|
163
|
+
## Releasing
|
|
164
|
+
|
|
165
|
+
1. Bump `version` in `pyproject.toml` and move the `Unreleased` entries in
|
|
166
|
+
[`CHANGELOG.md`](https://github.com/ch-rit/post_at_lib/blob/main/CHANGELOG.md)
|
|
167
|
+
to a new version section.
|
|
168
|
+
2. Commit, then tag and push:
|
|
169
|
+
|
|
170
|
+
```sh
|
|
171
|
+
git tag v0.1.0
|
|
172
|
+
git push origin main v0.1.0
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
3. The `Release` workflow checks that the tag matches the version in
|
|
176
|
+
`pyproject.toml`, builds sdist and wheel, publishes them to PyPI via trusted
|
|
177
|
+
publishing and creates a GitHub release with the files attached.
|
|
178
|
+
|
|
179
|
+
One-time setup:
|
|
180
|
+
|
|
181
|
+
- On [pypi.org](https://pypi.org/manage/account/publishing/) add a *pending
|
|
182
|
+
trusted publisher* for project `post-at-lib`: owner `ch-rit`, repository
|
|
183
|
+
`post_at_lib`, workflow `release.yaml`, environment `pypi`.
|
|
184
|
+
- In the GitHub repository settings, create an environment named `pypi`
|
|
185
|
+
(optionally with required reviewers or a `v*` tag rule).
|
|
186
|
+
|
|
187
|
+
## License
|
|
188
|
+
|
|
189
|
+
[MIT](https://github.com/ch-rit/post_at_lib/blob/main/LICENSE) © 2026 Christoph Ritzer
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "post-at-lib"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Unofficial client for the Österreichische Post (post.at) app API"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.11"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [{ name = "Christoph Ritzer", email = "c.ritzer@gmx.at" }]
|
|
14
|
+
keywords = ["post.at", "österreichische post", "austrian post", "parcel", "tracking", "shipment", "api-client"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 4 - Beta",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Operating System :: OS Independent",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
21
|
+
"Programming Language :: Python :: 3.11",
|
|
22
|
+
"Programming Language :: Python :: 3.12",
|
|
23
|
+
"Programming Language :: Python :: 3.13",
|
|
24
|
+
"Programming Language :: Python :: 3.14",
|
|
25
|
+
"Topic :: Home Automation",
|
|
26
|
+
"Typing :: Typed",
|
|
27
|
+
]
|
|
28
|
+
dependencies = ["httpx>=0.27", "pydantic>=2.11"]
|
|
29
|
+
|
|
30
|
+
[project.optional-dependencies]
|
|
31
|
+
test = ["pytest"]
|
|
32
|
+
|
|
33
|
+
[project.urls]
|
|
34
|
+
Homepage = "https://github.com/ch-rit/post_at_lib"
|
|
35
|
+
Source = "https://github.com/ch-rit/post_at_lib"
|
|
36
|
+
Issues = "https://github.com/ch-rit/post_at_lib/issues"
|
|
37
|
+
Changelog = "https://github.com/ch-rit/post_at_lib/blob/main/CHANGELOG.md"
|
|
38
|
+
|
|
39
|
+
[tool.hatch.build.targets.wheel]
|
|
40
|
+
packages = ["src/post_at"]
|
|
41
|
+
|
|
42
|
+
[tool.hatch.build.targets.sdist]
|
|
43
|
+
include = [
|
|
44
|
+
"/src",
|
|
45
|
+
"/tests",
|
|
46
|
+
"/scripts",
|
|
47
|
+
"/README.md",
|
|
48
|
+
"/CHANGELOG.md",
|
|
49
|
+
"/LICENSE",
|
|
50
|
+
"/pyproject.toml",
|
|
51
|
+
]
|
|
52
|
+
exclude = [
|
|
53
|
+
"__pycache__",
|
|
54
|
+
"*.pyc",
|
|
55
|
+
"/research",
|
|
56
|
+
"/captures",
|
|
57
|
+
"*.apkm",
|
|
58
|
+
".post_session.json",
|
|
59
|
+
]
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
"""Log in and dump the raw responses of every read-only endpoint to ``captures/``.
|
|
2
|
+
|
|
3
|
+
.venv/bin/python scripts/capture.py # e-mail/password prompt
|
|
4
|
+
.venv/bin/python scripts/capture.py --browser # sign in in a browser, paste the redirect URL
|
|
5
|
+
|
|
6
|
+
Personal values (names, addresses, e-mail, phone, ...) are masked unless
|
|
7
|
+
``--no-redact`` is given; structure, enums and status values are kept. Nothing is
|
|
8
|
+
modified on the account.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import argparse
|
|
14
|
+
import getpass
|
|
15
|
+
import json
|
|
16
|
+
import re
|
|
17
|
+
import sys
|
|
18
|
+
import traceback
|
|
19
|
+
from pathlib import Path
|
|
20
|
+
from typing import Any, Callable
|
|
21
|
+
|
|
22
|
+
from pydantic_core import to_jsonable_python
|
|
23
|
+
|
|
24
|
+
from post_at import ApiError, GraphQLError, PostAtClient
|
|
25
|
+
|
|
26
|
+
ROOT = Path(__file__).resolve().parent.parent
|
|
27
|
+
PII_KEY = re.compile(
|
|
28
|
+
r"name|street|strasse|email|mail|phone|mobile|number|birth|address(text)?$|recipient|consignee|"
|
|
29
|
+
r"sender|username|ssoid|crmid|customer|contact|person|city|postalcode|postcode|doornumber|housenumber|"
|
|
30
|
+
r"iban|token|identcode|identitycode|sendungsnummer|bezeichnung|bild|freetext|text$",
|
|
31
|
+
re.I,
|
|
32
|
+
)
|
|
33
|
+
# Keys that match PII_KEY but carry no personal data and are needed to model the API.
|
|
34
|
+
KEEP_KEY = re.compile(r"^(statusText|dueDateText|stateInfo|trackingState\w*|typeName|__typename|productName)$")
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def redact(value: Any, key: str = "") -> Any:
|
|
38
|
+
if isinstance(value, dict):
|
|
39
|
+
return {k: redact(v, k) for k, v in value.items()}
|
|
40
|
+
if isinstance(value, list):
|
|
41
|
+
return [redact(v, key) for v in value]
|
|
42
|
+
if isinstance(value, str) and value and PII_KEY.search(key) and not KEEP_KEY.match(key):
|
|
43
|
+
return f"<{key}:{len(value)}>"
|
|
44
|
+
if isinstance(value, (int, float)) and not isinstance(value, bool) and PII_KEY.search(key) and not KEEP_KEY.match(key):
|
|
45
|
+
return 0
|
|
46
|
+
return value
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def main() -> int:
|
|
50
|
+
parser = argparse.ArgumentParser()
|
|
51
|
+
parser.add_argument("--browser", action="store_true", help="log in through a browser instead of e-mail/password")
|
|
52
|
+
parser.add_argument("--no-redact", action="store_true", help="keep personal data in the dumps")
|
|
53
|
+
parser.add_argument("--out", type=Path, default=ROOT / "captures")
|
|
54
|
+
args = parser.parse_args()
|
|
55
|
+
args.out.mkdir(exist_ok=True)
|
|
56
|
+
|
|
57
|
+
with PostAtClient(session_file=ROOT / ".post_session.json") as post:
|
|
58
|
+
if not post.logged_in:
|
|
59
|
+
if args.browser:
|
|
60
|
+
pending = post.begin_browser_login()
|
|
61
|
+
print("1. Open devtools (F12) > Network, enable 'Preserve log'.")
|
|
62
|
+
print("2. Open this URL and sign in:\n\n" + pending.url + "\n")
|
|
63
|
+
print("3. Copy the msal228c4360-…://at.post.app/auth?code=… URL from the last")
|
|
64
|
+
print(" request's 'Location' response header (or the address bar).")
|
|
65
|
+
post.complete_browser_login(pending, input("redirect URL: ").strip())
|
|
66
|
+
else:
|
|
67
|
+
post.login(input("e-mail: ").strip(), getpass.getpass("password: "))
|
|
68
|
+
print("logged in; token claims:", sorted(post.session.claims))
|
|
69
|
+
|
|
70
|
+
def dump(name: str, call: Callable[[], Any]) -> Any:
|
|
71
|
+
entry: dict[str, Any]
|
|
72
|
+
result = None
|
|
73
|
+
try:
|
|
74
|
+
result = call()
|
|
75
|
+
# Models dump back to wire names; fields unknown to the models are kept.
|
|
76
|
+
entry = {"ok": True, "data": to_jsonable_python(result, by_alias=True)}
|
|
77
|
+
except ApiError as e:
|
|
78
|
+
entry = {"ok": False, "status": e.status_code, "operation_id": e.operation_id, "body": e.body}
|
|
79
|
+
except GraphQLError as e:
|
|
80
|
+
entry = {"ok": False, "graphql_errors": e.errors, "data": e.data}
|
|
81
|
+
except Exception: # keep going; the traceback is what we need to fix the client
|
|
82
|
+
entry = {"ok": False, "exception": traceback.format_exc()}
|
|
83
|
+
if not args.no_redact:
|
|
84
|
+
entry = redact(entry)
|
|
85
|
+
(args.out / f"{name}.json").write_text(json.dumps(entry, indent=2, ensure_ascii=False))
|
|
86
|
+
print(f"{'ok ' if entry['ok'] else 'ERR'} {name}")
|
|
87
|
+
return result
|
|
88
|
+
|
|
89
|
+
shipments = dump("shipments", post.shipments)
|
|
90
|
+
for i, item in enumerate(shipments.shipments[:3] if shipments else []):
|
|
91
|
+
number = item.tracking_number
|
|
92
|
+
dump(f"shipment_{i}", lambda: post.shipment(number))
|
|
93
|
+
dump(f"possible_redirections_{i}", lambda: post.possible_redirections(number))
|
|
94
|
+
dump(f"track_{i}", lambda: post.track(number))
|
|
95
|
+
|
|
96
|
+
dump("user", post.user)
|
|
97
|
+
dump("receiving_options", post.receiving_options)
|
|
98
|
+
dump("marketing_preferences", post.marketing_preferences)
|
|
99
|
+
dump("push_settings", post.push_settings)
|
|
100
|
+
dump("active_collection_services", post.active_collection_services)
|
|
101
|
+
dump("last_parcel_stamp_shipper_address", post.last_parcel_stamp_shipper_address)
|
|
102
|
+
orders = dump("order_history", lambda: post.order_history(limit=5, offset=0))
|
|
103
|
+
for i, order in enumerate(orders.orders[:2] if orders else []):
|
|
104
|
+
order_id = order.order_id
|
|
105
|
+
dump(f"order_details_{i}", lambda: post.order_details(order_id))
|
|
106
|
+
|
|
107
|
+
print(f"\nwrote {args.out}/ (session kept in .post_session.json; delete it to log out)")
|
|
108
|
+
return 0
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
if __name__ == "__main__":
|
|
112
|
+
sys.exit(main())
|