stalzone-api 0.1.0__py3-none-any.whl

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.
stalzone_api/client.py ADDED
@@ -0,0 +1,1033 @@
1
+ """High-level clients for the Stalzone API."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ from typing import Any, Iterable, Mapping
7
+ from urllib.parse import quote
8
+
9
+ from ._http import AsyncTransport, RateLimiter, SyncTransport
10
+ from .auth import (
11
+ AppSecretCredentials,
12
+ Credentials,
13
+ OAuth,
14
+ StaticTokenCredentials,
15
+ TokenCredentials,
16
+ UserInfo,
17
+ async_fetch_user_info,
18
+ fetch_user_info,
19
+ )
20
+ from .constants import (
21
+ DEFAULT_TIMEOUT,
22
+ DEMO_APP_SECRET,
23
+ DEMO_APP_TOKEN,
24
+ DEMO_APP_ID,
25
+ DEMO_URL,
26
+ DEMO_USER_TOKEN,
27
+ PROD_URL,
28
+ )
29
+ from .errors import AuthError
30
+ from .models.auction import LotPage, PricePage, PriceSummary
31
+ from .models.character import Character, CharacterProfile
32
+ from .models.clan import Clan, ClanList, ClanMember
33
+ from .models.common import Region, RegionInfo, format_datetime, region_value
34
+ from .models.emission import Emission
35
+ from .models.operations import SessionPage
36
+ from .pagination import paginate
37
+
38
+ __all__ = ["AsyncClient", "Client"]
39
+
40
+
41
+ def _resolve_region(region: str | Region | None, default: str | None) -> str:
42
+ value = region if region is not None else default
43
+ if value is None:
44
+ raise ValueError(
45
+ "region is required: pass region='EU' or create the client with Client(region='EU')"
46
+ )
47
+ return region_value(value)
48
+
49
+
50
+ def _env_credentials(
51
+ app_id: str | int | None,
52
+ app_secret: str | None,
53
+ access_token: str | None,
54
+ ) -> tuple[str | int | None, str | None, str | None]:
55
+ """Fill missing credentials from ``STALZONE_*`` environment variables.
56
+
57
+ Explicit arguments always win; a token from the environment takes precedence
58
+ over application credentials from the environment.
59
+ """
60
+
61
+ if access_token or app_id is not None or app_secret is not None:
62
+ return app_id, app_secret, access_token
63
+ env_token = os.environ.get("STALZONE_ACCESS_TOKEN")
64
+ if env_token:
65
+ return app_id, app_secret, env_token
66
+ env_id = os.environ.get("STALZONE_APP_ID")
67
+ env_secret = os.environ.get("STALZONE_APP_SECRET")
68
+ return env_id or None, env_secret or None, access_token
69
+
70
+
71
+ def _as_list(payload: Any, keys: Iterable[str] = ("data", "items", "members", "characters")) -> list[Any]:
72
+ if isinstance(payload, list):
73
+ return payload
74
+ if isinstance(payload, dict):
75
+ for key in keys:
76
+ value = payload.get(key)
77
+ if isinstance(value, list):
78
+ return value
79
+ for value in payload.values():
80
+ if isinstance(value, list):
81
+ return value
82
+ return []
83
+
84
+
85
+ def _lot_params(
86
+ offset: int | None,
87
+ limit: int | None,
88
+ sort: str | None,
89
+ order: str | None,
90
+ additional: bool | None,
91
+ ) -> dict[str, Any]:
92
+ return {
93
+ "offset": offset,
94
+ "limit": limit,
95
+ "sort": sort,
96
+ "order": order,
97
+ "additional": additional,
98
+ }
99
+
100
+
101
+ def _session_params(
102
+ *,
103
+ username: str | None,
104
+ limit: int | None,
105
+ offset: int | None,
106
+ after: Any,
107
+ before: Any,
108
+ map: str | None,
109
+ sort: str | None,
110
+ order: str | None,
111
+ ) -> dict[str, Any]:
112
+ return {
113
+ "username": username,
114
+ "limit": limit,
115
+ "offset": offset,
116
+ "after": format_datetime(after) if after is not None else None,
117
+ "before": format_datetime(before) if before is not None else None,
118
+ "map": map,
119
+ "sort": sort,
120
+ "order": order,
121
+ }
122
+
123
+
124
+ def _build_credentials(
125
+ *,
126
+ app_id: str | int | None,
127
+ app_secret: str | None,
128
+ access_token: str | None,
129
+ auth: str | None,
130
+ oauth: OAuth | None,
131
+ timeout: float,
132
+ user_agent: str | None,
133
+ on_token_update: Any,
134
+ ) -> tuple[Credentials | None, OAuth | None]:
135
+ if access_token:
136
+ return StaticTokenCredentials(access_token), oauth
137
+ if app_id is not None and app_secret:
138
+ mode = (auth or "secret").strip().lower()
139
+ if mode in ("secret", "headers", "client"):
140
+ return AppSecretCredentials(app_id, app_secret), oauth
141
+ if mode in ("token", "oauth", "client_credentials"):
142
+ oauth = oauth or OAuth(app_id, app_secret, timeout=timeout, user_agent=user_agent)
143
+ return TokenCredentials(oauth, on_update=on_token_update), oauth
144
+ raise ValueError("auth must be one of: 'secret', 'token'")
145
+ if app_id is not None or app_secret:
146
+ raise ValueError("app_id and app_secret must be provided together")
147
+ return None, oauth
148
+
149
+
150
+ # --------------------------------------------------------------------- resources
151
+ class AuctionAPI:
152
+ """Auction endpoints (``/{region}/auction/{item}/...``)."""
153
+
154
+ def __init__(self, client: "Client") -> None:
155
+ self._client = client
156
+
157
+ def lots(
158
+ self,
159
+ item: str,
160
+ *,
161
+ region: str | Region | None = None,
162
+ offset: int = 0,
163
+ limit: int = 20,
164
+ sort: str | None = None,
165
+ order: str | None = None,
166
+ additional: bool | None = None,
167
+ ) -> LotPage:
168
+ """Active lots for an item, sorted by ``time_created``/``time_left``/``current_price``/``buyout_price``."""
169
+
170
+ resolved = _resolve_region(region, self._client.region)
171
+ data = self._client.request(
172
+ "GET",
173
+ f"{resolved}/auction/{quote(str(item), safe='')}/lots",
174
+ params=_lot_params(offset, limit, sort, order, additional),
175
+ )
176
+ return LotPage.from_dict(data or {}, offset=offset)
177
+
178
+ def history(
179
+ self,
180
+ item: str,
181
+ *,
182
+ region: str | Region | None = None,
183
+ offset: int = 0,
184
+ limit: int = 20,
185
+ additional: bool | None = None,
186
+ ) -> PricePage:
187
+ """Completed purchases for an item, newest first."""
188
+
189
+ resolved = _resolve_region(region, self._client.region)
190
+ data = self._client.request(
191
+ "GET",
192
+ f"{resolved}/auction/{quote(str(item), safe='')}/history",
193
+ params=_lot_params(offset, limit, None, None, additional),
194
+ )
195
+ return PricePage.from_dict(data or {}, offset=offset)
196
+
197
+ def iter_lots(
198
+ self,
199
+ item: str,
200
+ *,
201
+ region: str | Region | None = None,
202
+ page_size: int = 200,
203
+ limit: int | None = None,
204
+ sort: str | None = None,
205
+ order: str | None = None,
206
+ additional: bool | None = None,
207
+ ):
208
+ """Iterate over every active lot, handling pagination automatically."""
209
+
210
+ def fetch(offset: int, size: int) -> LotPage:
211
+ return self.lots(
212
+ item,
213
+ region=region,
214
+ offset=offset,
215
+ limit=size,
216
+ sort=sort,
217
+ order=order,
218
+ additional=additional,
219
+ )
220
+
221
+ return paginate(fetch, page_size=page_size, limit=limit)
222
+
223
+ def iter_history(
224
+ self,
225
+ item: str,
226
+ *,
227
+ region: str | Region | None = None,
228
+ page_size: int = 200,
229
+ limit: int | None = None,
230
+ additional: bool | None = None,
231
+ ):
232
+ """Iterate over the full price history of an item."""
233
+
234
+ def fetch(offset: int, size: int) -> PricePage:
235
+ return self.history(item, region=region, offset=offset, limit=size, additional=additional)
236
+
237
+ return paginate(fetch, page_size=page_size, limit=limit)
238
+
239
+ def price_summary(
240
+ self,
241
+ item: str,
242
+ *,
243
+ region: str | Region | None = None,
244
+ limit: int = 200,
245
+ ) -> PriceSummary:
246
+ """Aggregate the latest ``limit`` purchases into min/max/mean/median values."""
247
+
248
+ page = self.history(item, region=region, limit=min(limit, 200))
249
+ prices = list(page.prices)
250
+ if limit > 200:
251
+ prices = list(self.iter_history(item, region=region, limit=limit, page_size=200))
252
+ return PriceSummary.from_prices(prices)
253
+
254
+
255
+ class CharactersAPI:
256
+ """Character endpoints."""
257
+
258
+ def __init__(self, client: "Client") -> None:
259
+ self._client = client
260
+
261
+ def list(self, *, region: str | Region | None = None) -> list[Character]:
262
+ """Characters of the user the access token belongs to (user token required)."""
263
+
264
+ resolved = _resolve_region(region, self._client.region)
265
+ data = self._client.request("GET", f"{resolved}/characters")
266
+ return [Character.from_dict(entry) for entry in _as_list(data)]
267
+
268
+ def profile(self, character: str, *, region: str | Region | None = None) -> CharacterProfile:
269
+ """Public character profile looked up by name (case-insensitive)."""
270
+
271
+ resolved = _resolve_region(region, self._client.region)
272
+ data = self._client.request(
273
+ "GET",
274
+ f"{resolved}/character/by-name/{quote(str(character), safe='')}/profile",
275
+ )
276
+ return CharacterProfile.from_dict(data or {})
277
+
278
+ def profile_by_uuid(self, uuid: str, *, region: str | Region | None = None) -> CharacterProfile:
279
+ """Public character profile looked up by its persistent UUID."""
280
+
281
+ resolved = _resolve_region(region, self._client.region)
282
+ data = self._client.request(
283
+ "GET",
284
+ f"{resolved}/character/by-uuid/{quote(str(uuid), safe='')}/profile",
285
+ )
286
+ return CharacterProfile.from_dict(data or {})
287
+
288
+
289
+ class ClansAPI:
290
+ """Clan endpoints."""
291
+
292
+ def __init__(self, client: "Client") -> None:
293
+ self._client = client
294
+
295
+ def list(
296
+ self,
297
+ *,
298
+ region: str | Region | None = None,
299
+ offset: int = 0,
300
+ limit: int = 200,
301
+ ) -> ClanList:
302
+ """All clans registered on the region (paginated)."""
303
+
304
+ resolved = _resolve_region(region, self._client.region)
305
+ data = self._client.request(
306
+ "GET",
307
+ f"{resolved}/clans",
308
+ params={"offset": offset, "limit": limit},
309
+ )
310
+ return ClanList.from_dict(data or {}, offset=offset)
311
+
312
+ def iter_all(
313
+ self,
314
+ *,
315
+ region: str | Region | None = None,
316
+ page_size: int = 200,
317
+ limit: int | None = None,
318
+ ):
319
+ """Iterate over every clan on the region."""
320
+
321
+ def fetch(offset: int, size: int) -> ClanList:
322
+ return self.list(region=region, offset=offset, limit=size)
323
+
324
+ return paginate(fetch, page_size=page_size, limit=limit)
325
+
326
+ def info(self, clan_id: str, *, region: str | Region | None = None) -> Clan:
327
+ resolved = _resolve_region(region, self._client.region)
328
+ data = self._client.request(
329
+ "GET",
330
+ f"{resolved}/clan/{quote(str(clan_id), safe='')}/info",
331
+ )
332
+ return Clan.from_dict(data or {})
333
+
334
+ def members(self, clan_id: str, *, region: str | Region | None = None) -> list[ClanMember]:
335
+ """Clan members (requires a user token of a clan member)."""
336
+
337
+ resolved = _resolve_region(region, self._client.region)
338
+ data = self._client.request(
339
+ "GET",
340
+ f"{resolved}/clan/{quote(str(clan_id), safe='')}/members",
341
+ )
342
+ return [ClanMember.from_dict(entry) for entry in _as_list(data)]
343
+
344
+
345
+ class OperationsAPI:
346
+ """Operation session endpoints."""
347
+
348
+ def __init__(self, client: "Client") -> None:
349
+ self._client = client
350
+
351
+ def sessions(
352
+ self,
353
+ *,
354
+ region: str | Region | None = None,
355
+ username: str | None = None,
356
+ limit: int = 100,
357
+ offset: int = 0,
358
+ after: Any = None,
359
+ before: Any = None,
360
+ map: str | None = None,
361
+ sort: str | None = None,
362
+ order: str | None = None,
363
+ ) -> SessionPage:
364
+ """List operation sessions (no authentication required)."""
365
+
366
+ resolved = _resolve_region(region, self._client.region)
367
+ data = self._client.request(
368
+ "GET",
369
+ f"{resolved}/operations/sessions",
370
+ params=_session_params(
371
+ username=username,
372
+ limit=limit,
373
+ offset=offset,
374
+ after=after,
375
+ before=before,
376
+ map=map,
377
+ sort=sort,
378
+ order=order,
379
+ ),
380
+ )
381
+ return SessionPage.from_dict(data or {}, offset=offset)
382
+
383
+ def iter_sessions(
384
+ self,
385
+ *,
386
+ region: str | Region | None = None,
387
+ username: str | None = None,
388
+ page_size: int = 100,
389
+ limit: int | None = None,
390
+ after: Any = None,
391
+ before: Any = None,
392
+ map: str | None = None,
393
+ sort: str | None = None,
394
+ order: str | None = None,
395
+ ):
396
+ def fetch(offset: int, size: int) -> SessionPage:
397
+ return self.sessions(
398
+ region=region,
399
+ username=username,
400
+ limit=size,
401
+ offset=offset,
402
+ after=after,
403
+ before=before,
404
+ map=map,
405
+ sort=sort,
406
+ order=order,
407
+ )
408
+
409
+ return paginate(fetch, page_size=page_size, limit=limit)
410
+
411
+
412
+ class Client:
413
+ """Synchronous client for the Stalzone API.
414
+
415
+ Three authentication modes are supported:
416
+
417
+ * ``Client(app_id=..., app_secret=...)`` — secret headers (stateless, default);
418
+ * ``Client(app_id=..., app_secret=..., auth="token")`` — OAuth client credentials;
419
+ * ``Client(access_token=...)`` — a user or application access token.
420
+ """
421
+
422
+ def __init__(
423
+ self,
424
+ *,
425
+ app_id: str | int | None = None,
426
+ app_secret: str | None = None,
427
+ access_token: str | None = None,
428
+ auth: str | None = None,
429
+ base_url: str = PROD_URL,
430
+ region: str | Region | None = None,
431
+ timeout: float = DEFAULT_TIMEOUT,
432
+ retries: int = 3,
433
+ backoff: float = 0.5,
434
+ user_agent: str | None = None,
435
+ rate_limit: float | None = None,
436
+ credentials: Credentials | None = None,
437
+ oauth: OAuth | None = None,
438
+ client: Any = None,
439
+ on_token_update: Any = None,
440
+ headers: Mapping[str, str] | None = None,
441
+ ) -> None:
442
+ self.region = region_value(region) if region is not None else None
443
+ self._oauth = oauth
444
+ if credentials is None:
445
+ app_id, app_secret, access_token = _env_credentials(app_id, app_secret, access_token)
446
+ credentials, self._oauth = _build_credentials(
447
+ app_id=app_id,
448
+ app_secret=app_secret,
449
+ access_token=access_token,
450
+ auth=auth,
451
+ oauth=oauth,
452
+ timeout=timeout,
453
+ user_agent=user_agent,
454
+ on_token_update=on_token_update,
455
+ )
456
+ self._credentials = credentials
457
+ self._rate_limiter = RateLimiter(rate_limit) if rate_limit else None
458
+ self._http = SyncTransport(
459
+ base_url,
460
+ credentials=credentials,
461
+ headers=headers,
462
+ timeout=timeout,
463
+ retries=retries,
464
+ backoff=backoff,
465
+ rate_limiter=self._rate_limiter,
466
+ user_agent=user_agent,
467
+ client=client,
468
+ )
469
+ self.auction = AuctionAPI(self)
470
+ self.characters = CharactersAPI(self)
471
+ self.clans = ClansAPI(self)
472
+ self.operations = OperationsAPI(self)
473
+
474
+ # ------------------------------------------------------------------- factory
475
+ @classmethod
476
+ def demo(
477
+ cls,
478
+ *,
479
+ user: bool = False,
480
+ token: str | None = None,
481
+ **kwargs: Any,
482
+ ) -> "Client":
483
+ """Client preconfigured for ``dapi.stalzone.com`` with the published demo token."""
484
+
485
+ kwargs.setdefault("base_url", DEMO_URL)
486
+ kwargs.setdefault("access_token", token or (DEMO_USER_TOKEN if user else DEMO_APP_TOKEN))
487
+ return cls(**kwargs)
488
+
489
+ @classmethod
490
+ def secret(
491
+ cls,
492
+ app_id: str | int,
493
+ app_secret: str,
494
+ **kwargs: Any,
495
+ ) -> "Client":
496
+ """Shortcut for the secret-headers authentication mode."""
497
+
498
+ kwargs.setdefault("base_url", DEMO_URL if app_id == DEMO_APP_ID and app_secret == DEMO_APP_SECRET else PROD_URL)
499
+ return cls(app_id=app_id, app_secret=app_secret, auth="secret", **kwargs)
500
+
501
+ @classmethod
502
+ def demo_secret(cls, **kwargs: Any) -> "Client":
503
+ kwargs.setdefault("base_url", DEMO_URL)
504
+ return cls(app_id=DEMO_APP_ID, app_secret=DEMO_APP_SECRET, auth="secret", **kwargs)
505
+
506
+ # ------------------------------------------------------------------ requests
507
+ def request(
508
+ self,
509
+ method: str,
510
+ path: str,
511
+ *,
512
+ params: Mapping[str, Any] | None = None,
513
+ headers: Mapping[str, str] | None = None,
514
+ ) -> Any:
515
+ """Escape hatch for calling a raw API path."""
516
+
517
+ return self._http.request(method, path, params=params, headers=headers)
518
+
519
+ def request_bytes(
520
+ self,
521
+ method: str,
522
+ path: str,
523
+ *,
524
+ params: Mapping[str, Any] | None = None,
525
+ headers: Mapping[str, str] | None = None,
526
+ ) -> bytes:
527
+ return self._http.request_bytes(method, path, params=params, headers=headers)
528
+
529
+ # ----------------------------------------------------------------- endpoints
530
+ def regions(self) -> list[RegionInfo]:
531
+ """List of regions available through the API."""
532
+
533
+ data = self.request("GET", "regions")
534
+ return [RegionInfo.from_dict(entry) for entry in _as_list(data)]
535
+
536
+ def emission(self, region: str | Region | None = None) -> Emission:
537
+ """Current and previous emission timestamps."""
538
+
539
+ resolved = _resolve_region(region, self.region)
540
+ return Emission.from_dict(self.request("GET", f"{resolved}/emission") or {})
541
+
542
+ def friends(self, character: str, *, region: str | Region | None = None) -> list[str]:
543
+ """Friend list of a character (requires a user token that owns the character)."""
544
+
545
+ resolved = _resolve_region(region, self.region)
546
+ data = self.request(
547
+ "GET",
548
+ f"{resolved}/friends/{quote(str(character), safe='')}",
549
+ )
550
+ result: list[str] = []
551
+ for entry in _as_list(data, keys=("friends", "data")):
552
+ if isinstance(entry, str):
553
+ result.append(entry)
554
+ elif isinstance(entry, dict):
555
+ name = entry.get("name") or entry.get("username") or entry.get("character")
556
+ if name:
557
+ result.append(str(name))
558
+ return result
559
+
560
+ def user_info(self) -> UserInfo:
561
+ """EXBO account of the current user access token (or of the app token owner)."""
562
+
563
+ if self._credentials is None:
564
+ raise AuthError("user_info() requires an access token")
565
+ token = self._credentials.ensure_token()
566
+ if not token:
567
+ raise AuthError("user_info() requires a user access token")
568
+ return fetch_user_info(token, timeout=self._http.timeout, user_agent=self._http.user_agent)
569
+
570
+ @property
571
+ def credentials(self) -> Credentials | None:
572
+ return self._credentials
573
+
574
+ @property
575
+ def oauth(self) -> OAuth | None:
576
+ return self._oauth
577
+
578
+ @property
579
+ def access_token(self) -> str | None:
580
+ """Current access token, if one is configured or can be obtained."""
581
+
582
+ if self._credentials is None:
583
+ return None
584
+ return self._credentials.ensure_token()
585
+
586
+ def close(self) -> None:
587
+ self._http.close()
588
+ if self._oauth is not None:
589
+ self._oauth.close()
590
+
591
+ def __enter__(self) -> "Client":
592
+ return self
593
+
594
+ def __exit__(self, *_: Any) -> None:
595
+ self.close()
596
+
597
+ def __repr__(self) -> str:
598
+ auth = type(self._credentials).__name__ if self._credentials else "none"
599
+ return f"Client(base_url={self._http.base_url!r}, auth={auth})"
600
+
601
+
602
+ # ------------------------------------------------------------------------- async
603
+ class AsyncAuctionAPI:
604
+ def __init__(self, client: "AsyncClient") -> None:
605
+ self._client = client
606
+
607
+ async def lots(
608
+ self,
609
+ item: str,
610
+ *,
611
+ region: str | Region | None = None,
612
+ offset: int = 0,
613
+ limit: int = 20,
614
+ sort: str | None = None,
615
+ order: str | None = None,
616
+ additional: bool | None = None,
617
+ ) -> LotPage:
618
+ resolved = _resolve_region(region, self._client.region)
619
+ data = await self._client.request(
620
+ "GET",
621
+ f"{resolved}/auction/{quote(str(item), safe='')}/lots",
622
+ params=_lot_params(offset, limit, sort, order, additional),
623
+ )
624
+ return LotPage.from_dict(data or {}, offset=offset)
625
+
626
+ async def history(
627
+ self,
628
+ item: str,
629
+ *,
630
+ region: str | Region | None = None,
631
+ offset: int = 0,
632
+ limit: int = 20,
633
+ additional: bool | None = None,
634
+ ) -> PricePage:
635
+ resolved = _resolve_region(region, self._client.region)
636
+ data = await self._client.request(
637
+ "GET",
638
+ f"{resolved}/auction/{quote(str(item), safe='')}/history",
639
+ params=_lot_params(offset, limit, None, None, additional),
640
+ )
641
+ return PricePage.from_dict(data or {}, offset=offset)
642
+
643
+ async def iter_lots(
644
+ self,
645
+ item: str,
646
+ *,
647
+ region: str | Region | None = None,
648
+ page_size: int = 200,
649
+ limit: int | None = None,
650
+ sort: str | None = None,
651
+ order: str | None = None,
652
+ additional: bool | None = None,
653
+ ):
654
+ offset = 0
655
+ produced = 0
656
+ while True:
657
+ page = await self.lots(
658
+ item,
659
+ region=region,
660
+ offset=offset,
661
+ limit=page_size,
662
+ sort=sort,
663
+ order=order,
664
+ additional=additional,
665
+ )
666
+ for lot in page.lots:
667
+ yield lot
668
+ produced += 1
669
+ if limit is not None and produced >= limit:
670
+ return
671
+ if page.is_last:
672
+ return
673
+ offset += len(page.lots)
674
+
675
+ async def iter_history(
676
+ self,
677
+ item: str,
678
+ *,
679
+ region: str | Region | None = None,
680
+ page_size: int = 200,
681
+ limit: int | None = None,
682
+ additional: bool | None = None,
683
+ ):
684
+ offset = 0
685
+ produced = 0
686
+ while True:
687
+ page = await self.history(
688
+ item, region=region, offset=offset, limit=page_size, additional=additional
689
+ )
690
+ for entry in page.prices:
691
+ yield entry
692
+ produced += 1
693
+ if limit is not None and produced >= limit:
694
+ return
695
+ if page.is_last:
696
+ return
697
+ offset += len(page.prices)
698
+
699
+ async def price_summary(
700
+ self,
701
+ item: str,
702
+ *,
703
+ region: str | Region | None = None,
704
+ limit: int = 200,
705
+ ) -> PriceSummary:
706
+ if limit <= 200:
707
+ page = await self.history(item, region=region, limit=limit)
708
+ return PriceSummary.from_prices(page.prices)
709
+ prices = [entry async for entry in self.iter_history(item, region=region, limit=limit)]
710
+ return PriceSummary.from_prices(prices)
711
+
712
+
713
+ class AsyncCharactersAPI:
714
+ def __init__(self, client: "AsyncClient") -> None:
715
+ self._client = client
716
+
717
+ async def list(self, *, region: str | Region | None = None) -> list[Character]:
718
+ resolved = _resolve_region(region, self._client.region)
719
+ data = await self._client.request("GET", f"{resolved}/characters")
720
+ return [Character.from_dict(entry) for entry in _as_list(data)]
721
+
722
+ async def profile(self, character: str, *, region: str | Region | None = None) -> CharacterProfile:
723
+ resolved = _resolve_region(region, self._client.region)
724
+ data = await self._client.request(
725
+ "GET",
726
+ f"{resolved}/character/by-name/{quote(str(character), safe='')}/profile",
727
+ )
728
+ return CharacterProfile.from_dict(data or {})
729
+
730
+ async def profile_by_uuid(self, uuid: str, *, region: str | Region | None = None) -> CharacterProfile:
731
+ resolved = _resolve_region(region, self._client.region)
732
+ data = await self._client.request(
733
+ "GET",
734
+ f"{resolved}/character/by-uuid/{quote(str(uuid), safe='')}/profile",
735
+ )
736
+ return CharacterProfile.from_dict(data or {})
737
+
738
+
739
+ class AsyncClansAPI:
740
+ def __init__(self, client: "AsyncClient") -> None:
741
+ self._client = client
742
+
743
+ async def list(
744
+ self,
745
+ *,
746
+ region: str | Region | None = None,
747
+ offset: int = 0,
748
+ limit: int = 200,
749
+ ) -> ClanList:
750
+ resolved = _resolve_region(region, self._client.region)
751
+ data = await self._client.request(
752
+ "GET",
753
+ f"{resolved}/clans",
754
+ params={"offset": offset, "limit": limit},
755
+ )
756
+ return ClanList.from_dict(data or {}, offset=offset)
757
+
758
+ async def iter_all(
759
+ self,
760
+ *,
761
+ region: str | Region | None = None,
762
+ page_size: int = 200,
763
+ limit: int | None = None,
764
+ ):
765
+ offset = 0
766
+ produced = 0
767
+ while True:
768
+ page = await self.list(region=region, offset=offset, limit=page_size)
769
+ for clan in page.data:
770
+ yield clan
771
+ produced += 1
772
+ if limit is not None and produced >= limit:
773
+ return
774
+ if page.is_last:
775
+ return
776
+ offset += len(page.data)
777
+
778
+ async def info(self, clan_id: str, *, region: str | Region | None = None) -> Clan:
779
+ resolved = _resolve_region(region, self._client.region)
780
+ data = await self._client.request(
781
+ "GET",
782
+ f"{resolved}/clan/{quote(str(clan_id), safe='')}/info",
783
+ )
784
+ return Clan.from_dict(data or {})
785
+
786
+ async def members(self, clan_id: str, *, region: str | Region | None = None) -> list[ClanMember]:
787
+ resolved = _resolve_region(region, self._client.region)
788
+ data = await self._client.request(
789
+ "GET",
790
+ f"{resolved}/clan/{quote(str(clan_id), safe='')}/members",
791
+ )
792
+ return [ClanMember.from_dict(entry) for entry in _as_list(data)]
793
+
794
+
795
+ class AsyncOperationsAPI:
796
+ def __init__(self, client: "AsyncClient") -> None:
797
+ self._client = client
798
+
799
+ async def sessions(
800
+ self,
801
+ *,
802
+ region: str | Region | None = None,
803
+ username: str | None = None,
804
+ limit: int = 100,
805
+ offset: int = 0,
806
+ after: Any = None,
807
+ before: Any = None,
808
+ map: str | None = None,
809
+ sort: str | None = None,
810
+ order: str | None = None,
811
+ ) -> SessionPage:
812
+ resolved = _resolve_region(region, self._client.region)
813
+ data = await self._client.request(
814
+ "GET",
815
+ f"{resolved}/operations/sessions",
816
+ params=_session_params(
817
+ username=username,
818
+ limit=limit,
819
+ offset=offset,
820
+ after=after,
821
+ before=before,
822
+ map=map,
823
+ sort=sort,
824
+ order=order,
825
+ ),
826
+ )
827
+ return SessionPage.from_dict(data or {}, offset=offset)
828
+
829
+ async def iter_sessions(
830
+ self,
831
+ *,
832
+ region: str | Region | None = None,
833
+ username: str | None = None,
834
+ page_size: int = 100,
835
+ limit: int | None = None,
836
+ after: Any = None,
837
+ before: Any = None,
838
+ map: str | None = None,
839
+ sort: str | None = None,
840
+ order: str | None = None,
841
+ ):
842
+ offset = 0
843
+ produced = 0
844
+ while True:
845
+ page = await self.sessions(
846
+ region=region,
847
+ username=username,
848
+ limit=page_size,
849
+ offset=offset,
850
+ after=after,
851
+ before=before,
852
+ map=map,
853
+ sort=sort,
854
+ order=order,
855
+ )
856
+ for session in page.sessions:
857
+ yield session
858
+ produced += 1
859
+ if limit is not None and produced >= limit:
860
+ return
861
+ if page.is_last:
862
+ return
863
+ offset += len(page.sessions)
864
+
865
+
866
+ class AsyncClient:
867
+ """Asynchronous counterpart of :class:`Client` (same API surface, ``await`` everything)."""
868
+
869
+ def __init__(
870
+ self,
871
+ *,
872
+ app_id: str | int | None = None,
873
+ app_secret: str | None = None,
874
+ access_token: str | None = None,
875
+ auth: str | None = None,
876
+ base_url: str = PROD_URL,
877
+ region: str | Region | None = None,
878
+ timeout: float = DEFAULT_TIMEOUT,
879
+ retries: int = 3,
880
+ backoff: float = 0.5,
881
+ user_agent: str | None = None,
882
+ rate_limit: float | None = None,
883
+ credentials: Credentials | None = None,
884
+ oauth: OAuth | None = None,
885
+ client: Any = None,
886
+ on_token_update: Any = None,
887
+ headers: Mapping[str, str] | None = None,
888
+ ) -> None:
889
+ self.region = region_value(region) if region is not None else None
890
+ self._oauth = oauth
891
+ if credentials is None:
892
+ app_id, app_secret, access_token = _env_credentials(app_id, app_secret, access_token)
893
+ credentials, self._oauth = _build_credentials(
894
+ app_id=app_id,
895
+ app_secret=app_secret,
896
+ access_token=access_token,
897
+ auth=auth,
898
+ oauth=oauth,
899
+ timeout=timeout,
900
+ user_agent=user_agent,
901
+ on_token_update=on_token_update,
902
+ )
903
+ self._credentials = credentials
904
+ self._rate_limiter = RateLimiter(rate_limit) if rate_limit else None
905
+ self._http = AsyncTransport(
906
+ base_url,
907
+ credentials=credentials,
908
+ headers=headers,
909
+ timeout=timeout,
910
+ retries=retries,
911
+ backoff=backoff,
912
+ rate_limiter=self._rate_limiter,
913
+ user_agent=user_agent,
914
+ client=client,
915
+ )
916
+ self.auction = AsyncAuctionAPI(self)
917
+ self.characters = AsyncCharactersAPI(self)
918
+ self.clans = AsyncClansAPI(self)
919
+ self.operations = AsyncOperationsAPI(self)
920
+
921
+ @classmethod
922
+ def demo(
923
+ cls,
924
+ *,
925
+ user: bool = False,
926
+ token: str | None = None,
927
+ **kwargs: Any,
928
+ ) -> "AsyncClient":
929
+ kwargs.setdefault("base_url", DEMO_URL)
930
+ kwargs.setdefault("access_token", token or (DEMO_USER_TOKEN if user else DEMO_APP_TOKEN))
931
+ return cls(**kwargs)
932
+
933
+ @classmethod
934
+ def secret(cls, app_id: str | int, app_secret: str, **kwargs: Any) -> "AsyncClient":
935
+ kwargs.setdefault("base_url", DEMO_URL if app_id == DEMO_APP_ID and app_secret == DEMO_APP_SECRET else PROD_URL)
936
+ return cls(app_id=app_id, app_secret=app_secret, auth="secret", **kwargs)
937
+
938
+ @classmethod
939
+ def demo_secret(cls, **kwargs: Any) -> "AsyncClient":
940
+ kwargs.setdefault("base_url", DEMO_URL)
941
+ return cls(app_id=DEMO_APP_ID, app_secret=DEMO_APP_SECRET, auth="secret", **kwargs)
942
+
943
+ async def request(
944
+ self,
945
+ method: str,
946
+ path: str,
947
+ *,
948
+ params: Mapping[str, Any] | None = None,
949
+ headers: Mapping[str, str] | None = None,
950
+ ) -> Any:
951
+ return await self._http.request(method, path, params=params, headers=headers)
952
+
953
+ async def request_bytes(
954
+ self,
955
+ method: str,
956
+ path: str,
957
+ *,
958
+ params: Mapping[str, Any] | None = None,
959
+ headers: Mapping[str, str] | None = None,
960
+ ) -> bytes:
961
+ return await self._http.request_bytes(method, path, params=params, headers=headers)
962
+
963
+ async def regions(self) -> list[RegionInfo]:
964
+ data = await self.request("GET", "regions")
965
+ return [RegionInfo.from_dict(entry) for entry in _as_list(data)]
966
+
967
+ async def emission(self, region: str | Region | None = None) -> Emission:
968
+ resolved = _resolve_region(region, self.region)
969
+ return Emission.from_dict(await self.request("GET", f"{resolved}/emission") or {})
970
+
971
+ async def friends(self, character: str, *, region: str | Region | None = None) -> list[str]:
972
+ resolved = _resolve_region(region, self.region)
973
+ data = await self.request(
974
+ "GET",
975
+ f"{resolved}/friends/{quote(str(character), safe='')}",
976
+ )
977
+ result: list[str] = []
978
+ for entry in _as_list(data, keys=("friends", "data")):
979
+ if isinstance(entry, str):
980
+ result.append(entry)
981
+ elif isinstance(entry, dict):
982
+ name = entry.get("name") or entry.get("username") or entry.get("character")
983
+ if name:
984
+ result.append(str(name))
985
+ return result
986
+
987
+ async def user_info(self) -> UserInfo:
988
+ if self._credentials is None:
989
+ raise AuthError("user_info() requires an access token")
990
+ token = await self._credentials.async_ensure_token()
991
+ if not token:
992
+ raise AuthError("user_info() requires a user access token")
993
+ return await async_fetch_user_info(
994
+ token, timeout=self._http.timeout, user_agent=self._http.user_agent
995
+ )
996
+
997
+ @property
998
+ def credentials(self) -> Credentials | None:
999
+ return self._credentials
1000
+
1001
+ @property
1002
+ def oauth(self) -> OAuth | None:
1003
+ return self._oauth
1004
+
1005
+ @property
1006
+ def access_token(self) -> str | None:
1007
+ """Cached access token (may be ``None`` until the first request)."""
1008
+
1009
+ if self._credentials is None:
1010
+ return None
1011
+ return self._credentials.token
1012
+
1013
+ async def fetch_access_token(self) -> str | None:
1014
+ """Return an access token, obtaining or refreshing it when needed."""
1015
+
1016
+ if self._credentials is None:
1017
+ return None
1018
+ return await self._credentials.async_ensure_token()
1019
+
1020
+ async def close(self) -> None:
1021
+ await self._http.aclose()
1022
+ if self._oauth is not None:
1023
+ await self._oauth.aclose()
1024
+
1025
+ async def __aenter__(self) -> "AsyncClient":
1026
+ return self
1027
+
1028
+ async def __aexit__(self, *_: Any) -> None:
1029
+ await self.close()
1030
+
1031
+ def __repr__(self) -> str:
1032
+ auth = type(self._credentials).__name__ if self._credentials else "none"
1033
+ return f"AsyncClient(base_url={self._http.base_url!r}, auth={auth})"