stalzone-api 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 (48) hide show
  1. stalzone_api-0.1.0/.gitignore +10 -0
  2. stalzone_api-0.1.0/CHANGELOG.md +15 -0
  3. stalzone_api-0.1.0/LICENSE +21 -0
  4. stalzone_api-0.1.0/PKG-INFO +213 -0
  5. stalzone_api-0.1.0/README.md +184 -0
  6. stalzone_api-0.1.0/docs/analysis.md +117 -0
  7. stalzone_api-0.1.0/docs/authentication.md +121 -0
  8. stalzone_api-0.1.0/docs/clients-and-api.md +144 -0
  9. stalzone_api-0.1.0/docs/database.md +133 -0
  10. stalzone_api-0.1.0/docs/development.md +77 -0
  11. stalzone_api-0.1.0/docs/index.md +47 -0
  12. stalzone_api-0.1.0/docs/installation.md +48 -0
  13. stalzone_api-0.1.0/docs/models-and-errors.md +101 -0
  14. stalzone_api-0.1.0/pyproject.toml +50 -0
  15. stalzone_api-0.1.0/src/stalzone_api/__init__.py +228 -0
  16. stalzone_api-0.1.0/src/stalzone_api/_http.py +375 -0
  17. stalzone_api-0.1.0/src/stalzone_api/_version.py +3 -0
  18. stalzone_api-0.1.0/src/stalzone_api/auth.py +525 -0
  19. stalzone_api-0.1.0/src/stalzone_api/client.py +1033 -0
  20. stalzone_api-0.1.0/src/stalzone_api/constants.py +32 -0
  21. stalzone_api-0.1.0/src/stalzone_api/database/__init__.py +165 -0
  22. stalzone_api-0.1.0/src/stalzone_api/database/cache.py +146 -0
  23. stalzone_api-0.1.0/src/stalzone_api/database/icons.py +90 -0
  24. stalzone_api-0.1.0/src/stalzone_api/database/index.py +135 -0
  25. stalzone_api-0.1.0/src/stalzone_api/database/items.py +692 -0
  26. stalzone_api-0.1.0/src/stalzone_api/database/providers.py +393 -0
  27. stalzone_api-0.1.0/src/stalzone_api/errors.py +138 -0
  28. stalzone_api-0.1.0/src/stalzone_api/models/__init__.py +41 -0
  29. stalzone_api-0.1.0/src/stalzone_api/models/auction.py +217 -0
  30. stalzone_api-0.1.0/src/stalzone_api/models/character.py +188 -0
  31. stalzone_api-0.1.0/src/stalzone_api/models/clan.py +146 -0
  32. stalzone_api-0.1.0/src/stalzone_api/models/common.py +162 -0
  33. stalzone_api-0.1.0/src/stalzone_api/models/emission.py +44 -0
  34. stalzone_api-0.1.0/src/stalzone_api/models/operations.py +149 -0
  35. stalzone_api-0.1.0/src/stalzone_api/pagination.py +50 -0
  36. stalzone_api-0.1.0/src/stalzone_api/py.typed +0 -0
  37. stalzone_api-0.1.0/src/stalzone_api/simple.py +403 -0
  38. stalzone_api-0.1.0/tests/conftest.py +106 -0
  39. stalzone_api-0.1.0/tests/test_auth.py +177 -0
  40. stalzone_api-0.1.0/tests/test_client_async.py +122 -0
  41. stalzone_api-0.1.0/tests/test_client_sync.py +310 -0
  42. stalzone_api-0.1.0/tests/test_database.py +326 -0
  43. stalzone_api-0.1.0/tests/test_errors.py +71 -0
  44. stalzone_api-0.1.0/tests/test_http.py +147 -0
  45. stalzone_api-0.1.0/tests/test_integration.py +46 -0
  46. stalzone_api-0.1.0/tests/test_models.py +237 -0
  47. stalzone_api-0.1.0/tests/test_pagination.py +61 -0
  48. stalzone_api-0.1.0/tests/test_simple.py +155 -0
@@ -0,0 +1,10 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ venv/
5
+ dist/
6
+ build/
7
+ *.egg-info/
8
+ .pytest_cache/
9
+ .mypy_cache/
10
+ .ruff_cache/
@@ -0,0 +1,15 @@
1
+ # Changelog
2
+
3
+ Notable user-facing changes are listed here. The project follows semantic
4
+ versioning once it reaches a stable public API.
5
+
6
+ ## 0.1.0 — initial release
7
+
8
+ - Synchronous and asynchronous Stalzone API clients.
9
+ - Simple `AppClient` and `SyncAppClient` facades with environment credential
10
+ lookup and the public demo server fallback.
11
+ - OAuth helpers, typed response models, pagination, retries, rate limiting,
12
+ and API error mapping.
13
+ - Read-only access to the official Stalcraft item database from GitHub, local
14
+ checkouts, or downloaded snapshots, including item search and icons.
15
+ - Python 3.10+ support and PEP 561 typing marker.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 stalzone-api contributors
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,213 @@
1
+ Metadata-Version: 2.5
2
+ Name: stalzone-api
3
+ Version: 0.1.0
4
+ Summary: Python client for the Stalzone API (Stalcraft) and the official items database
5
+ Project-URL: Homepage, https://github.com/Oneyann/stalzone-api
6
+ Project-URL: Repository, https://github.com/Oneyann/stalzone-api
7
+ Project-URL: Issues, https://github.com/Oneyann/stalzone-api/issues
8
+ Author: stalzone-api contributors
9
+ License: MIT
10
+ License-File: LICENSE
11
+ Keywords: api,exbo,game,oauth,stalcraft,stalzone
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Typing :: Typed
21
+ Requires-Python: >=3.10
22
+ Requires-Dist: httpx>=0.27
23
+ Provides-Extra: gui
24
+ Requires-Dist: pyside6>=6.6; extra == 'gui'
25
+ Provides-Extra: test
26
+ Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
27
+ Requires-Dist: pytest>=8; extra == 'test'
28
+ Description-Content-Type: text/markdown
29
+
30
+ # stalzone-api
31
+
32
+ The simplest Python client for the **Stalzone API** (Stalcraft) and the official
33
+ **items database**. One import, one client, no boilerplate.
34
+
35
+ ```bash
36
+ pip install stalzone-api
37
+ ```
38
+
39
+ ## 30-second start
40
+
41
+ ```python
42
+ import asyncio
43
+ from stalzone_api import AppClient
44
+
45
+ async def main():
46
+ async with AppClient() as client: # env vars, or the demo server
47
+ print(await client.emission())
48
+ print(await client.profile("ZIV"))
49
+ print(await client.auction("zyv9").lots(limit=3))
50
+
51
+ asyncio.run(main())
52
+ ```
53
+
54
+ `AppClient()` reads credentials from the environment; if none are set it
55
+ automatically uses the public demo server. It always works.
56
+
57
+ No `async`? Use the identical synchronous facade:
58
+
59
+ ```python
60
+ from stalzone_api import SyncAppClient
61
+
62
+ with SyncAppClient() as client:
63
+ print(client.emission())
64
+ print(client.profile("ZIV"))
65
+ print(client.auction("zyv9").lots(limit=3))
66
+ ```
67
+
68
+ Objects know how to print themselves:
69
+
70
+ ```
71
+ Emission: inactive, last ended 2026-11-19 10:24 UTC
72
+ ZIV · 105 stats
73
+ 3 of 93
74
+ zyv9: 100 x 1 (ends 2026-11-19 22:50)
75
+ zyv9: 100 x 1 (ends 2026-11-21 10:49)
76
+ zyv9: 1 x 1 (ends 2026-11-21 10:44)
77
+ ```
78
+
79
+ ## Authentication
80
+
81
+ | Variable | Meaning |
82
+ | --- | --- |
83
+ | `STALZONE_APP_ID` (or `CLIENT_ID`) | application id (`Client-Id`) |
84
+ | `STALZONE_APP_SECRET` (or `CLIENT_SECRET`) | application secret (`Client-Secret`) |
85
+ | `STALZONE_ACCESS_TOKEN` (or `APP_TOKEN`) | ready bearer token — wins over id/secret |
86
+
87
+ Explicit values work too:
88
+
89
+ ```python
90
+ AppClient(client_id=123, client_secret="…", region="RU")
91
+ AppClient(token="eyJ0eXAiOiJKV1Qi…")
92
+ AppClient.demo() # public demo server
93
+ ```
94
+
95
+ Region defaults to `RU`; pass `region="EU"` or `region=Region.EU` to change it.
96
+
97
+ ## Everything the simple client can do
98
+
99
+ ```python
100
+ await client.regions() # list of regions
101
+ await client.emission() # emission status
102
+ await client.profile("ZIV") # public profile by name
103
+ await client.profile("uuid…", uuid=True) # by uuid
104
+ await client.characters() # characters visible to the token
105
+ await client.friends("ZIV") # friend names
106
+ await client.clans(limit=20) # clan list
107
+ await client.sessions(limit=20, map="big_cleanup")
108
+ await client.request("GET", "RU/regions") # any raw endpoint
109
+
110
+ auction = client.auction("zyv9")
111
+ await auction.lots(limit=20, sort="current_price", order="asc")
112
+ await auction.history(limit=50)
113
+ await auction.summary(limit=200) # min / mean / median / max
114
+ await auction.all_lots() # every page, automatically
115
+ ```
116
+
117
+ `SyncAppClient` has the same methods without `await`.
118
+
119
+ ## Items database
120
+
121
+ ```python
122
+ from stalzone_api import Database
123
+
124
+ db = Database("ru").sync() # one request: download a full offline snapshot
125
+ db = Database.local("./stalzone-database") # or use your own local clone
126
+
127
+ item = db.items.get("knmpy")
128
+ print(item.name.ru, item.weight, item.damage)
129
+
130
+ for found in db.items.search("винторез", lang="ru", limit=5):
131
+ print(found.id, found.name.en)
132
+
133
+ png = db.icons.bytes("knmpy")
134
+ ```
135
+
136
+ On-demand GitHub loading also works (`Database("ru")`), but the snapshot or a
137
+ local clone is recommended for search and bulk access. GitHub responds with
138
+ `403` when the unauthenticated rate limit is exhausted; set
139
+ `STALZONE_GITHUB_TOKEN`, use `.sync()` once, or call `Database.local(...)`.
140
+
141
+ ## Advanced API
142
+
143
+ The low-level clients are still available when you need full control:
144
+ `Client` and `AsyncClient` expose resources `auction`, `characters`, `clans`
145
+ and `operations`, plus `regions()`, `emission()`, `friends()`, `user_info()`
146
+ and raw `request()` / `request_bytes()`.
147
+
148
+ ```python
149
+ from stalzone_api import Client
150
+
151
+ with Client(app_id=123, app_secret="…", region="EU") as client:
152
+ page = client.auction.lots("y1q9", limit=20)
153
+ for lot in page:
154
+ print(lot.price, lot.end_time)
155
+ for session in client.operations.iter_sessions(map="shock_therapy"):
156
+ print(session.id, len(session.participants))
157
+ ```
158
+
159
+ Features of the core layer:
160
+
161
+ * both sync and async clients with the same API;
162
+ * automatic pagination via `iter_lots`, `iter_history`, `clans.iter_all`,
163
+ `operations.iter_sessions`; pages expose `items`, `total`, `offset`,
164
+ `next_offset`, `is_last`;
165
+ * retries on `429`/`5xx` and network errors with exponential backoff and
166
+ `Retry-After`, optional `rate_limit=`;
167
+ * typed dataclass models; unknown API fields stay in `.extra`, unknown item
168
+ blocks/elements become `RawBlock` / `RawElement`;
169
+ * OAuth 2.0 helpers: `OAuth(...).authorize_url()`, `exchange_code()`,
170
+ `refresh()`, `client_credentials()`, `user_info()`;
171
+ * precise errors: `BadRequest`, `Unauthorized`, `Forbidden`, `NotFound`,
172
+ `RateLimited`, `ServerError`, `TransportError`;
173
+ * `auth="token"` for OAuth client credentials, `Client.demo(user=True)` for the
174
+ demo server, percent-encoded names and int64 session ids handled for you.
175
+
176
+ Client options: `base_url`, `region`, `timeout`, `retries`, `backoff`,
177
+ `user_agent`, `rate_limit`, `headers`. A `User-Agent` is always sent —
178
+ Cloudflare rejects requests without it.
179
+
180
+ ## Tests
181
+
182
+ ```bash
183
+ python -m pip install -e ".[test]"
184
+ python -m pytest -q
185
+ ```
186
+
187
+ No network is needed (`httpx.MockTransport`). Live requests are opt-in:
188
+
189
+ ```bash
190
+ $env:STALZONE_RUN_INTEGRATION="1"
191
+ python -m pytest -m integration
192
+ ```
193
+
194
+ ## Documentation
195
+
196
+ The detailed guides are in [`docs/`](docs/index.md):
197
+
198
+ * [Installation and supported Python versions](docs/installation.md)
199
+ * [Clients and API endpoint reference](docs/clients-and-api.md)
200
+ * [Authentication and OAuth](docs/authentication.md)
201
+ * [Items database](docs/database.md)
202
+ * [Models, pagination, and errors](docs/models-and-errors.md)
203
+ * [Architecture and code analysis](docs/analysis.md)
204
+ * [Development and release](docs/development.md)
205
+
206
+ ## Changelog
207
+
208
+ See [`CHANGELOG.md`](CHANGELOG.md).
209
+
210
+ ## Disclaimer
211
+
212
+ Unofficial library. Stalcraft, Stalzone and the items database belong to EXBO.
213
+ MIT license.
@@ -0,0 +1,184 @@
1
+ # stalzone-api
2
+
3
+ The simplest Python client for the **Stalzone API** (Stalcraft) and the official
4
+ **items database**. One import, one client, no boilerplate.
5
+
6
+ ```bash
7
+ pip install stalzone-api
8
+ ```
9
+
10
+ ## 30-second start
11
+
12
+ ```python
13
+ import asyncio
14
+ from stalzone_api import AppClient
15
+
16
+ async def main():
17
+ async with AppClient() as client: # env vars, or the demo server
18
+ print(await client.emission())
19
+ print(await client.profile("ZIV"))
20
+ print(await client.auction("zyv9").lots(limit=3))
21
+
22
+ asyncio.run(main())
23
+ ```
24
+
25
+ `AppClient()` reads credentials from the environment; if none are set it
26
+ automatically uses the public demo server. It always works.
27
+
28
+ No `async`? Use the identical synchronous facade:
29
+
30
+ ```python
31
+ from stalzone_api import SyncAppClient
32
+
33
+ with SyncAppClient() as client:
34
+ print(client.emission())
35
+ print(client.profile("ZIV"))
36
+ print(client.auction("zyv9").lots(limit=3))
37
+ ```
38
+
39
+ Objects know how to print themselves:
40
+
41
+ ```
42
+ Emission: inactive, last ended 2026-11-19 10:24 UTC
43
+ ZIV · 105 stats
44
+ 3 of 93
45
+ zyv9: 100 x 1 (ends 2026-11-19 22:50)
46
+ zyv9: 100 x 1 (ends 2026-11-21 10:49)
47
+ zyv9: 1 x 1 (ends 2026-11-21 10:44)
48
+ ```
49
+
50
+ ## Authentication
51
+
52
+ | Variable | Meaning |
53
+ | --- | --- |
54
+ | `STALZONE_APP_ID` (or `CLIENT_ID`) | application id (`Client-Id`) |
55
+ | `STALZONE_APP_SECRET` (or `CLIENT_SECRET`) | application secret (`Client-Secret`) |
56
+ | `STALZONE_ACCESS_TOKEN` (or `APP_TOKEN`) | ready bearer token — wins over id/secret |
57
+
58
+ Explicit values work too:
59
+
60
+ ```python
61
+ AppClient(client_id=123, client_secret="…", region="RU")
62
+ AppClient(token="eyJ0eXAiOiJKV1Qi…")
63
+ AppClient.demo() # public demo server
64
+ ```
65
+
66
+ Region defaults to `RU`; pass `region="EU"` or `region=Region.EU` to change it.
67
+
68
+ ## Everything the simple client can do
69
+
70
+ ```python
71
+ await client.regions() # list of regions
72
+ await client.emission() # emission status
73
+ await client.profile("ZIV") # public profile by name
74
+ await client.profile("uuid…", uuid=True) # by uuid
75
+ await client.characters() # characters visible to the token
76
+ await client.friends("ZIV") # friend names
77
+ await client.clans(limit=20) # clan list
78
+ await client.sessions(limit=20, map="big_cleanup")
79
+ await client.request("GET", "RU/regions") # any raw endpoint
80
+
81
+ auction = client.auction("zyv9")
82
+ await auction.lots(limit=20, sort="current_price", order="asc")
83
+ await auction.history(limit=50)
84
+ await auction.summary(limit=200) # min / mean / median / max
85
+ await auction.all_lots() # every page, automatically
86
+ ```
87
+
88
+ `SyncAppClient` has the same methods without `await`.
89
+
90
+ ## Items database
91
+
92
+ ```python
93
+ from stalzone_api import Database
94
+
95
+ db = Database("ru").sync() # one request: download a full offline snapshot
96
+ db = Database.local("./stalzone-database") # or use your own local clone
97
+
98
+ item = db.items.get("knmpy")
99
+ print(item.name.ru, item.weight, item.damage)
100
+
101
+ for found in db.items.search("винторез", lang="ru", limit=5):
102
+ print(found.id, found.name.en)
103
+
104
+ png = db.icons.bytes("knmpy")
105
+ ```
106
+
107
+ On-demand GitHub loading also works (`Database("ru")`), but the snapshot or a
108
+ local clone is recommended for search and bulk access. GitHub responds with
109
+ `403` when the unauthenticated rate limit is exhausted; set
110
+ `STALZONE_GITHUB_TOKEN`, use `.sync()` once, or call `Database.local(...)`.
111
+
112
+ ## Advanced API
113
+
114
+ The low-level clients are still available when you need full control:
115
+ `Client` and `AsyncClient` expose resources `auction`, `characters`, `clans`
116
+ and `operations`, plus `regions()`, `emission()`, `friends()`, `user_info()`
117
+ and raw `request()` / `request_bytes()`.
118
+
119
+ ```python
120
+ from stalzone_api import Client
121
+
122
+ with Client(app_id=123, app_secret="…", region="EU") as client:
123
+ page = client.auction.lots("y1q9", limit=20)
124
+ for lot in page:
125
+ print(lot.price, lot.end_time)
126
+ for session in client.operations.iter_sessions(map="shock_therapy"):
127
+ print(session.id, len(session.participants))
128
+ ```
129
+
130
+ Features of the core layer:
131
+
132
+ * both sync and async clients with the same API;
133
+ * automatic pagination via `iter_lots`, `iter_history`, `clans.iter_all`,
134
+ `operations.iter_sessions`; pages expose `items`, `total`, `offset`,
135
+ `next_offset`, `is_last`;
136
+ * retries on `429`/`5xx` and network errors with exponential backoff and
137
+ `Retry-After`, optional `rate_limit=`;
138
+ * typed dataclass models; unknown API fields stay in `.extra`, unknown item
139
+ blocks/elements become `RawBlock` / `RawElement`;
140
+ * OAuth 2.0 helpers: `OAuth(...).authorize_url()`, `exchange_code()`,
141
+ `refresh()`, `client_credentials()`, `user_info()`;
142
+ * precise errors: `BadRequest`, `Unauthorized`, `Forbidden`, `NotFound`,
143
+ `RateLimited`, `ServerError`, `TransportError`;
144
+ * `auth="token"` for OAuth client credentials, `Client.demo(user=True)` for the
145
+ demo server, percent-encoded names and int64 session ids handled for you.
146
+
147
+ Client options: `base_url`, `region`, `timeout`, `retries`, `backoff`,
148
+ `user_agent`, `rate_limit`, `headers`. A `User-Agent` is always sent —
149
+ Cloudflare rejects requests without it.
150
+
151
+ ## Tests
152
+
153
+ ```bash
154
+ python -m pip install -e ".[test]"
155
+ python -m pytest -q
156
+ ```
157
+
158
+ No network is needed (`httpx.MockTransport`). Live requests are opt-in:
159
+
160
+ ```bash
161
+ $env:STALZONE_RUN_INTEGRATION="1"
162
+ python -m pytest -m integration
163
+ ```
164
+
165
+ ## Documentation
166
+
167
+ The detailed guides are in [`docs/`](docs/index.md):
168
+
169
+ * [Installation and supported Python versions](docs/installation.md)
170
+ * [Clients and API endpoint reference](docs/clients-and-api.md)
171
+ * [Authentication and OAuth](docs/authentication.md)
172
+ * [Items database](docs/database.md)
173
+ * [Models, pagination, and errors](docs/models-and-errors.md)
174
+ * [Architecture and code analysis](docs/analysis.md)
175
+ * [Development and release](docs/development.md)
176
+
177
+ ## Changelog
178
+
179
+ See [`CHANGELOG.md`](CHANGELOG.md).
180
+
181
+ ## Disclaimer
182
+
183
+ Unofficial library. Stalcraft, Stalzone and the items database belong to EXBO.
184
+ MIT license.
@@ -0,0 +1,117 @@
1
+ # Architecture and code analysis
2
+
3
+ This page records the package structure and behavior review for version
4
+ `0.1.0`. It is a code-reading analysis, not a guarantee about upstream API
5
+ behavior. Findings are separated from documented behavior and should be
6
+ rechecked against later versions.
7
+
8
+ ## Architecture
9
+
10
+ ```text
11
+ AppClient / SyncAppClient
12
+ |
13
+ Client / AsyncClient
14
+ / | \
15
+ resources auth HTTP transport
16
+ | |
17
+ models httpx / retries
18
+
19
+ Database
20
+ |-- GitHubProvider -- DiskCache
21
+ |-- LocalProvider
22
+ |-- ItemStore / ItemIndex
23
+ `-- IconStore
24
+ ```
25
+
26
+ - `simple.py` is the convenience facade. It selects demo, token, or secret
27
+ auth and delegates to the low-level client.
28
+ - `client.py` defines sync/async endpoint resources and maps JSON responses
29
+ into model objects.
30
+ - `auth.py` handles OAuth token operations and credential providers.
31
+ - `_http.py` centralizes URL construction, headers, rate limiting, retries,
32
+ JSON parsing, and HTTP-status-to-exception conversion.
33
+ - `models/` contains typed API responses and tolerant parsing of unknown
34
+ fields.
35
+ - `database/` provides GitHub/local file sources, disk caching, item parsing,
36
+ lookup/search indexes, and icon access.
37
+ - `tests/` covers unit, mock-transport, auth, models, pagination, and opt-in
38
+ integration behavior.
39
+
40
+ ## Review findings
41
+
42
+ ### Medium: synchronous price summary can fetch the first page twice
43
+
44
+ `src/stalzone_api/client.py`, `AuctionAPI.price_summary` first fetches history
45
+ with a cap of 200, then when `limit > 200` replaces that result with
46
+ `iter_history(...)`, which starts again from offset zero. This duplicates
47
+ work/network traffic for the common `limit > 200` case. The async
48
+ implementation does not make this initial extra request. The resulting
49
+ summary data should still cover the requested history limit, but the
50
+ sync/async request counts differ.
51
+
52
+ ### Medium: transport retries all HTTP methods
53
+
54
+ `src/stalzone_api/_http.py`, `SyncTransport._execute` and
55
+ `AsyncTransport._execute` retry network failures and configured transient
56
+ statuses without checking the HTTP method. This is appropriate for GET-like
57
+ operations, but raw `request()` supports arbitrary methods. A POST or another
58
+ non-idempotent operation could be applied more than once if the server
59
+ processed it but the response was lost, or returned a retryable status after
60
+ partial processing. Callers should avoid relying on automatic retries for
61
+ non-idempotent operations.
62
+
63
+ ### Low: unexpected list payloads may be interpreted permissively
64
+
65
+ `src/stalzone_api/client.py`, `_as_list` looks first for known list-valued
66
+ keys, then returns the first list found anywhere in a dictionary. This makes
67
+ the client tolerant of response wrappers, but a changed or unexpected
68
+ response schema can yield an unrelated list rather than an explicit parse
69
+ failure. Review such responses when upstream schemas change.
70
+
71
+ ### Low: pagination stops based on server totals and empty pages
72
+
73
+ `src/stalzone_api/pagination.py`, `paginate` stops on an empty page or when
74
+ `offset + len(items) >= total`. If the upstream total is missing, stale, or
75
+ inconsistent, iteration may stop earlier than expected (or continue until an
76
+ empty page). The current models normalize absent totals to zero, which makes
77
+ the `is_last` calculation especially dependent on the API returning a valid
78
+ total.
79
+
80
+ ### Security note: JWT decoding does not verify signatures
81
+
82
+ `src/stalzone_api/auth.py`, `decode_jwt` decodes only the payload. Its
83
+ docstring correctly says it does not verify signatures. Never use values
84
+ returned by this helper as proof of identity, authorization, or token
85
+ validity.
86
+
87
+ ## Positive design properties
88
+
89
+ - Sync and async transports and resource classes are intentionally parallel.
90
+ - Context manager support makes HTTP resource cleanup straightforward.
91
+ - `httpx` injection and mock transports make unit tests independent of the
92
+ live service.
93
+ - API error subclasses preserve status and response details.
94
+ - Unknown API fields and unknown item database block/element kinds are
95
+ retained rather than discarded.
96
+ - GitHub-backed database reads use caching, ETags, and stale JSON fallback;
97
+ the archive extractor validates member paths before extraction.
98
+ - Tests are opt-in for live API calls; ordinary unit test runs do not require
99
+ network access.
100
+
101
+ ## Verification performed for this review
102
+
103
+ - `python -m pytest -q`: **85 passed, 2 skipped**.
104
+ - The skipped tests are live integration tests and require
105
+ `STALZONE_RUN_INTEGRATION=1`.
106
+ - No code behavior was changed as part of writing this documentation.
107
+
108
+ ## Suggested follow-up
109
+
110
+ 1. Add a regression test for sync/async `price_summary` request counts when
111
+ the requested limit exceeds 200.
112
+ 2. Consider allowing retries only for safe/idempotent methods by default, or
113
+ making retry behavior configurable per request.
114
+ 3. Add malformed/unexpected API response tests around `_as_list` and
115
+ pagination totals.
116
+ 4. Keep the sync and async implementations covered by paired tests whenever
117
+ endpoint behavior changes.
@@ -0,0 +1,121 @@
1
+ # Authentication and OAuth
2
+
3
+ ## Credential selection
4
+
5
+ The simple facades look for credentials in this order:
6
+
7
+ 1. Explicit constructor arguments.
8
+ 2. Environment variables.
9
+ 3. Public demo server, unless `demo=False` was requested.
10
+
11
+ Environment variable aliases:
12
+
13
+ | Purpose | Preferred variable | Alias |
14
+ | --- | --- | --- |
15
+ | Application ID | `STALZONE_APP_ID` | `CLIENT_ID` |
16
+ | Application secret | `STALZONE_APP_SECRET` | `CLIENT_SECRET` |
17
+ | Access token | `STALZONE_ACCESS_TOKEN` | `APP_TOKEN` |
18
+
19
+ For the low-level `Client` and `AsyncClient`, the documented environment
20
+ lookup is `STALZONE_APP_ID`, `STALZONE_APP_SECRET`, and
21
+ `STALZONE_ACCESS_TOKEN`. An explicit access token takes precedence over the
22
+ other values in the simple facade. Keep production credentials in a secret
23
+ manager or environment configuration; never commit them.
24
+
25
+ To require configured credentials rather than silently falling back to the
26
+ demo:
27
+
28
+ ```python
29
+ client = AppClient(demo=False)
30
+ ```
31
+
32
+ ## Authentication modes
33
+
34
+ ### Secret headers
35
+
36
+ The low-level client defaults to application secret headers when both
37
+ `app_id` and `app_secret` are provided:
38
+
39
+ ```python
40
+ client = Client(app_id="123", app_secret="secret", region="EU")
41
+ ```
42
+
43
+ Requests carry `Client-Id` and `Client-Secret` headers. This is the default
44
+ `auth="secret"` mode.
45
+
46
+ ### Bearer token
47
+
48
+ Supply a token obtained separately:
49
+
50
+ ```python
51
+ client = AsyncClient(access_token="access-token", region="RU")
52
+ ```
53
+
54
+ The token is sent as an `Authorization: Bearer ...` header. The simple facade
55
+ accepts the token as `AppClient(token=...)`.
56
+
57
+ ### OAuth client credentials
58
+
59
+ Use `auth="token"` with application ID and secret to request an application
60
+ token and refresh it automatically when needed:
61
+
62
+ ```python
63
+ client = AsyncClient(
64
+ app_id="123",
65
+ app_secret="secret",
66
+ auth="token",
67
+ region="RU",
68
+ )
69
+ ```
70
+
71
+ The low-level clients also expose their `oauth` helper and
72
+ `fetch_access_token()` on `AsyncClient`. The synchronous `access_token`
73
+ property may obtain a token when needed; the async property's value is the
74
+ cached token, so use `await client.fetch_access_token()` to ensure one has
75
+ been obtained.
76
+
77
+ ## Authorization-code flow
78
+
79
+ The `OAuth` class provides URL construction, code exchange, refresh,
80
+ client-credentials, and user-info operations:
81
+
82
+ ```python
83
+ from stalzone_api import OAuth
84
+
85
+ oauth = OAuth("client-id", "client-secret")
86
+ url = oauth.authorize_url(
87
+ "https://your-app.example/callback",
88
+ state="random-csrf-token",
89
+ scope="",
90
+ )
91
+ # Redirect the user to `url`; validate returned state in your application.
92
+ token = oauth.exchange_code(
93
+ "authorization-code",
94
+ "https://your-app.example/callback",
95
+ )
96
+ print(token.access_token)
97
+ ```
98
+
99
+ `OAuth` has matching `async_*` methods for asynchronous applications:
100
+ `async_exchange_code`, `async_refresh`, `async_client_credentials`, and
101
+ `async_user_info`. `Token` exposes `access_token`, `token_type`,
102
+ `expires_in`, `refresh_token`, `scope`, `expires_at`, `is_expired()`,
103
+ `authorization()`, and `to_dict()`.
104
+
105
+ State generation, callback routing, state validation, and secure storage of
106
+ tokens are application responsibilities. The helper builds the authorization
107
+ URL but does not run a browser or callback server.
108
+
109
+ ## Token inspection warning
110
+
111
+ `decode_jwt()` and `Token.payload` decode a JWT payload without validating its
112
+ signature. Use them only to inspect claims for debugging; decoded claims must
113
+ not be trusted for authorization or security decisions.
114
+
115
+ ## User-only endpoints
116
+
117
+ Some endpoints require a suitable user token rather than application
118
+ credentials, including listing the token owner's characters, friends, clan
119
+ members, and account `user_info()`. The API remains authoritative about
120
+ permissions; expect `Unauthorized` or `Forbidden` if the token is absent or
121
+ does not have the required access.