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.
Files changed (43) hide show
  1. post_at_lib-0.1.0/.gitignore +14 -0
  2. post_at_lib-0.1.0/CHANGELOG.md +44 -0
  3. post_at_lib-0.1.0/LICENSE +21 -0
  4. post_at_lib-0.1.0/PKG-INFO +219 -0
  5. post_at_lib-0.1.0/README.md +189 -0
  6. post_at_lib-0.1.0/pyproject.toml +59 -0
  7. post_at_lib-0.1.0/scripts/capture.py +112 -0
  8. post_at_lib-0.1.0/src/post_at/__init__.py +26 -0
  9. post_at_lib-0.1.0/src/post_at/auth.py +292 -0
  10. post_at_lib-0.1.0/src/post_at/client.py +617 -0
  11. post_at_lib-0.1.0/src/post_at/errors.py +41 -0
  12. post_at_lib-0.1.0/src/post_at/graphql/AddShipmentInbound.graphql +1 -0
  13. post_at_lib-0.1.0/src/post_at/graphql/AddShipmentOutbound.graphql +1 -0
  14. post_at_lib-0.1.0/src/post_at/graphql/BoundingBox.graphql +1 -0
  15. post_at_lib-0.1.0/src/post_at/graphql/PossibleRedirections.graphql +1 -0
  16. post_at_lib-0.1.0/src/post_at/graphql/RedirectShipmentNeighbor.graphql +1 -0
  17. post_at_lib-0.1.0/src/post_at/graphql/RedirectShipmentParcelLocker.graphql +1 -0
  18. post_at_lib-0.1.0/src/post_at/graphql/RedirectShipmentPlace.graphql +1 -0
  19. post_at_lib-0.1.0/src/post_at/graphql/RedirectShipmentPostOffice.graphql +1 -0
  20. post_at_lib-0.1.0/src/post_at/graphql/RemoveShipmentInbound.graphql +1 -0
  21. post_at_lib-0.1.0/src/post_at/graphql/RemoveShipmentOutbound.graphql +1 -0
  22. post_at_lib-0.1.0/src/post_at/graphql/RenameShipment.graphql +1 -0
  23. post_at_lib-0.1.0/src/post_at/graphql/ResetNeighborShipmentRedirection.graphql +1 -0
  24. post_at_lib-0.1.0/src/post_at/graphql/ResetParcelLockerShipmentRedirection.graphql +1 -0
  25. post_at_lib-0.1.0/src/post_at/graphql/ResetPlaceShipmentRedirection.graphql +1 -0
  26. post_at_lib-0.1.0/src/post_at/graphql/ResetPostOfficeShipmentRedirection.graphql +1 -0
  27. post_at_lib-0.1.0/src/post_at/graphql/ShipmentAuth.graphql +1 -0
  28. post_at_lib-0.1.0/src/post_at/graphql/ShipmentList.graphql +1 -0
  29. post_at_lib-0.1.0/src/post_at/graphql/ShipmentPublic.graphql +1 -0
  30. post_at_lib-0.1.0/src/post_at/models.py +619 -0
  31. post_at_lib-0.1.0/src/post_at/py.typed +0 -0
  32. post_at_lib-0.1.0/tests/fixtures/last_parcel_stamp_shipper_address.json +12 -0
  33. post_at_lib-0.1.0/tests/fixtures/marketing_preferences.json +111 -0
  34. post_at_lib-0.1.0/tests/fixtures/order_details.json +87 -0
  35. post_at_lib-0.1.0/tests/fixtures/order_history.json +26 -0
  36. post_at_lib-0.1.0/tests/fixtures/possible_redirections.json +114 -0
  37. post_at_lib-0.1.0/tests/fixtures/push_settings.json +89 -0
  38. post_at_lib-0.1.0/tests/fixtures/receiving_options.json +21 -0
  39. post_at_lib-0.1.0/tests/fixtures/shipment.json +159 -0
  40. post_at_lib-0.1.0/tests/fixtures/shipments.json +348 -0
  41. post_at_lib-0.1.0/tests/fixtures/track.json +123 -0
  42. post_at_lib-0.1.0/tests/fixtures/user.json +43 -0
  43. 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
+ [![PyPI](https://img.shields.io/pypi/v/post-at-lib)](https://pypi.org/project/post-at-lib/)
38
+ [![Python versions](https://img.shields.io/pypi/pyversions/post-at-lib)](https://pypi.org/project/post-at-lib/)
39
+ [![License: MIT](https://img.shields.io/github/license/ch-rit/post_at_lib)](https://github.com/ch-rit/post_at_lib/blob/main/LICENSE)
40
+ [![Tests](https://github.com/ch-rit/post_at_lib/actions/workflows/tests.yaml/badge.svg)](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
+ [![PyPI](https://img.shields.io/pypi/v/post-at-lib)](https://pypi.org/project/post-at-lib/)
8
+ [![Python versions](https://img.shields.io/pypi/pyversions/post-at-lib)](https://pypi.org/project/post-at-lib/)
9
+ [![License: MIT](https://img.shields.io/github/license/ch-rit/post_at_lib)](https://github.com/ch-rit/post_at_lib/blob/main/LICENSE)
10
+ [![Tests](https://github.com/ch-rit/post_at_lib/actions/workflows/tests.yaml/badge.svg)](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())