hyper-sdk 4.2.0__tar.gz → 4.3.2__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 (41) hide show
  1. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/PKG-INFO +13 -1
  2. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/README.md +12 -0
  3. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/akamai/sec_cpt.py +133 -129
  4. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/datadome/parse.py +17 -12
  5. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/results.py +42 -1
  6. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/session.py +28 -1
  7. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/session_async.py +29 -1
  8. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk.egg-info/PKG-INFO +13 -1
  9. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk.egg-info/SOURCES.txt +2 -0
  10. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/pyproject.toml +1 -1
  11. hyper_sdk-4.3.2/tests/test_challenge_script_url.py +68 -0
  12. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/tests/test_results.py +60 -0
  13. hyper_sdk-4.3.2/tests/test_sec_cpt.py +69 -0
  14. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/LICENSE +0 -0
  15. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/__init__.py +0 -0
  16. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/akamai/__init__.py +0 -0
  17. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/akamai/pixel.py +0 -0
  18. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/akamai/script_path.py +0 -0
  19. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/akamai/stop_signal.py +0 -0
  20. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/akamai_input.py +0 -0
  21. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/datadome/__init__.py +0 -0
  22. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/datadome_input.py +0 -0
  23. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/incapsula/__init__.py +0 -0
  24. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/incapsula/dynamic.py +0 -0
  25. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/incapsula/utmvc.py +0 -0
  26. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/incapsula_input.py +0 -0
  27. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/kasada/__init__.py +0 -0
  28. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/kasada/dv.py +0 -0
  29. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/kasada/parse.py +0 -0
  30. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/kasada/user_agent.py +0 -0
  31. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/kasada_input.py +0 -0
  32. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/payloads.py +0 -0
  33. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/shared.py +0 -0
  34. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk/trustdecision_input.py +0 -0
  35. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk.egg-info/dependency_links.txt +0 -0
  36. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk.egg-info/requires.txt +0 -0
  37. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/hyper_sdk.egg-info/top_level.txt +0 -0
  38. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/setup.cfg +0 -0
  39. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/tests/test_dv.py +0 -0
  40. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/tests/test_script_hash.py +0 -0
  41. {hyper_sdk-4.2.0 → hyper_sdk-4.3.2}/tests/test_user_agent.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: hyper_sdk
3
- Version: 4.2.0
3
+ Version: 4.3.2
4
4
  Summary: Hyper Solutions Python SDK
5
5
  License: MIT License
6
6
 
@@ -146,6 +146,18 @@ session = Session(
146
146
  )
147
147
  ```
148
148
 
149
+ ### Checking Usage
150
+
151
+ `get_usage` returns the key's pay-as-you-go balance and the remaining requests of each plan. It is not counted as usage. `SessionAsync` has the same method.
152
+
153
+ ```python
154
+ usage = session.get_usage()
155
+
156
+ print(f"balance: €{usage.balance_euro}")
157
+ for plan in usage.plans:
158
+ print(f"{plan.product}: {plan.requests_remaining} of {plan.requests_quota} left, expires {plan.expires_at}")
159
+ ```
160
+
149
161
  ## 🛡️ Akamai Bot Manager
150
162
 
151
163
  Bypass **Akamai Bot Manager** protection with sensor data generation, cookie validation, and challenge solving.
@@ -103,6 +103,18 @@ session = Session(
103
103
  )
104
104
  ```
105
105
 
106
+ ### Checking Usage
107
+
108
+ `get_usage` returns the key's pay-as-you-go balance and the remaining requests of each plan. It is not counted as usage. `SessionAsync` has the same method.
109
+
110
+ ```python
111
+ usage = session.get_usage()
112
+
113
+ print(f"balance: €{usage.balance_euro}")
114
+ for plan in usage.plans:
115
+ print(f"{plan.product}: {plan.requests_remaining} of {plan.requests_quota} left, expires {plan.expires_at}")
116
+ ```
117
+
106
118
  ## 🛡️ Akamai Bot Manager
107
119
 
108
120
  Bypass **Akamai Bot Manager** protection with sensor data generation, cookie validation, and challenge solving.
@@ -1,130 +1,134 @@
1
- import base64
2
- import hashlib
3
- import json
4
- import os
5
- import re
6
- import time
7
- from collections import OrderedDict
8
- from typing import List
9
-
10
- sec_duration_expr = re.compile(r'data-duration=(\d+)')
11
- sec_challenge_expr = re.compile(r'challenge="(.*?)"')
12
- sec_page_expr = re.compile(r'data-duration=\d+\s+src="([^"]+)"')
13
-
14
-
15
- class SecCptChallengeData:
16
- def __init__(self, token: str, timestamp: int, nonce: str, difficulty: int, count: int):
17
- self.token = token
18
- self.timestamp = timestamp
19
- self.nonce = nonce
20
- self.difficulty = difficulty
21
- self.count = count
22
-
23
-
24
- class SecCptChallenge:
25
- def __init__(self, duration: int, challenge_path: str, challenge_data: SecCptChallengeData):
26
- self.duration = duration
27
- self.challenge_path = challenge_path
28
- self.challenge_data = challenge_data
29
-
30
- @staticmethod
31
- def parse(html: str) -> 'SecCptChallenge':
32
- challenge_data = SecCptChallenge._parse_challenge_data(html)
33
- duration = SecCptChallenge._parse_duration(html)
34
- challenge_path = SecCptChallenge._parse_challenge_path(html)
35
-
36
- return SecCptChallenge(duration, challenge_path, challenge_data)
37
-
38
- @staticmethod
39
- def parse_from_json(json_payload: str) -> 'SecCptChallenge':
40
- api_response = json.loads(json_payload)
41
-
42
- challenge_data = SecCptChallengeData(
43
- api_response.get('token', ''),
44
- api_response.get('timestamp', 0),
45
- api_response.get('nonce', ''),
46
- api_response.get('difficulty', 0)
47
- )
48
-
49
- duration = api_response.get('chlg_duration', 0)
50
- challenge_path = api_response.get('branding_url_content', '')
51
-
52
- return SecCptChallenge(duration, challenge_path, challenge_data)
53
-
54
- @staticmethod
55
- def _parse_challenge_data(src: str) -> SecCptChallengeData:
56
- challenge_match = sec_challenge_expr.search(src)
57
- if not challenge_match:
58
- raise Exception("hyper-sdk: Challenge data not found.")
59
-
60
- decoded_challenge = base64.b64decode(challenge_match.group(1))
61
- challenge_data = json.loads(decoded_challenge)
62
-
63
- return SecCptChallengeData(
64
- challenge_data.get('token', ''),
65
- challenge_data.get('timestamp', 0),
66
- challenge_data.get('nonce', ''),
67
- challenge_data.get('difficulty', 0),
68
- challenge_data.get('count', 0)
69
- )
70
-
71
- @staticmethod
72
- def _parse_duration(src: str) -> int:
73
- duration_match = sec_duration_expr.search(src)
74
- if not duration_match:
75
- raise Exception("hyper-sdk: Duration not found.")
76
-
77
- try:
78
- duration = int(duration_match.group(1))
79
- except ValueError as e:
80
- raise Exception(f"hyper-sdk: Invalid duration value: {e}")
81
-
82
- return duration
83
-
84
- @staticmethod
85
- def _parse_challenge_path(src: str) -> str:
86
- page_match = sec_page_expr.search(src)
87
- if not page_match:
88
- raise Exception("hyper-sdk: Challenge path not found.")
89
-
90
- return page_match.group(1)
91
-
92
- def generate_sec_cpt_payload(self, sec_cpt_cookie: str) -> str:
93
- sec, _, _ = sec_cpt_cookie.partition("~")
94
- if sec == sec_cpt_cookie:
95
- raise Exception("hyper-sdk: Malformed sec_cpt cookie.")
96
-
97
- answers = self._generate_sec_cpt_answers(sec)
98
-
99
- payload = OrderedDict([
100
- ("token", self.challenge_data.token),
101
- ("answers", answers)
102
- ])
103
-
104
- return json.dumps(payload)
105
-
106
- def sleep(self):
107
- time.sleep(self.duration)
108
-
109
- def _generate_sec_cpt_answers(self, sec: str) -> List[str]:
110
- answers = []
111
- difficulty = self.challenge_data.difficulty
112
-
113
- while True:
114
- answer = f"0.{os.urandom(8).hex()}"
115
- hash_input = f"{sec}{self.challenge_data.timestamp}{self.challenge_data.nonce}{difficulty}{answer}"
116
-
117
- output = 0
118
- for byte in hashlib.sha256(hash_input.encode('ascii')).digest():
119
- output = (output << 8) | byte
120
- output %= difficulty
121
-
122
- if output == 0:
123
- difficulty += 1
124
- answers.append(answer)
125
-
126
- if len(answers) == self.challenge_data.count:
127
- break
128
- continue
129
-
1
+ import base64
2
+ import hashlib
3
+ import json
4
+ import os
5
+ import re
6
+ import time
7
+ from collections import OrderedDict
8
+ from typing import List
9
+
10
+ sec_duration_expr = re.compile(r'data-duration=(\d+)')
11
+ sec_challenge_expr = re.compile(r'challenge="(.*?)"')
12
+ sec_page_expr = re.compile(r'data-duration=\d+\s+src="([^"]+)"')
13
+
14
+
15
+ class SecCptChallengeData:
16
+ def __init__(self, token: str, timestamp: int, nonce: str, difficulty: int, count: int):
17
+ self.token = token
18
+ self.timestamp = timestamp
19
+ self.nonce = nonce
20
+ self.difficulty = difficulty
21
+ self.count = count
22
+
23
+
24
+ class SecCptChallenge:
25
+ def __init__(self, duration: int, challenge_path: str, challenge_data: SecCptChallengeData):
26
+ self.duration = duration
27
+ self.challenge_path = challenge_path
28
+ self.challenge_data = challenge_data
29
+
30
+ @staticmethod
31
+ def parse(html: str) -> 'SecCptChallenge':
32
+ challenge_data = SecCptChallenge._parse_challenge_data(html)
33
+ duration = SecCptChallenge._parse_duration(html)
34
+ challenge_path = SecCptChallenge._parse_challenge_path(html)
35
+
36
+ return SecCptChallenge(duration, challenge_path, challenge_data)
37
+
38
+ @staticmethod
39
+ def parse_from_json(json_payload: str) -> 'SecCptChallenge':
40
+ api_response = json.loads(json_payload)
41
+
42
+ challenge_data = SecCptChallengeData(
43
+ api_response.get('token', ''),
44
+ api_response.get('timestamp', 0),
45
+ api_response.get('nonce', ''),
46
+ api_response.get('difficulty', 0),
47
+ api_response.get('count', 0)
48
+ )
49
+
50
+ duration = api_response.get('chlg_duration', 0)
51
+ challenge_path = api_response.get('branding_url_content', '')
52
+
53
+ return SecCptChallenge(duration, challenge_path, challenge_data)
54
+
55
+ @staticmethod
56
+ def _parse_challenge_data(src: str) -> SecCptChallengeData:
57
+ challenge_match = sec_challenge_expr.search(src)
58
+ if not challenge_match:
59
+ raise Exception("hyper-sdk: Challenge data not found.")
60
+
61
+ decoded_challenge = base64.b64decode(challenge_match.group(1))
62
+ challenge_data = json.loads(decoded_challenge)
63
+
64
+ return SecCptChallengeData(
65
+ challenge_data.get('token', ''),
66
+ challenge_data.get('timestamp', 0),
67
+ challenge_data.get('nonce', ''),
68
+ challenge_data.get('difficulty', 0),
69
+ challenge_data.get('count', 0)
70
+ )
71
+
72
+ @staticmethod
73
+ def _parse_duration(src: str) -> int:
74
+ duration_match = sec_duration_expr.search(src)
75
+ if not duration_match:
76
+ raise Exception("hyper-sdk: Duration not found.")
77
+
78
+ try:
79
+ duration = int(duration_match.group(1))
80
+ except ValueError as e:
81
+ raise Exception(f"hyper-sdk: Invalid duration value: {e}")
82
+
83
+ return duration
84
+
85
+ @staticmethod
86
+ def _parse_challenge_path(src: str) -> str:
87
+ page_match = sec_page_expr.search(src)
88
+ if not page_match:
89
+ raise Exception("hyper-sdk: Challenge path not found.")
90
+
91
+ return page_match.group(1)
92
+
93
+ def generate_sec_cpt_payload(self, sec_cpt_cookie: str) -> str:
94
+ sec, _, _ = sec_cpt_cookie.partition("~")
95
+ if sec == sec_cpt_cookie:
96
+ raise Exception("hyper-sdk: Malformed sec_cpt cookie.")
97
+
98
+ answers = self._generate_sec_cpt_answers(sec)
99
+
100
+ payload = OrderedDict([
101
+ ("token", self.challenge_data.token),
102
+ ("answers", answers)
103
+ ])
104
+
105
+ return json.dumps(payload)
106
+
107
+ def sleep(self):
108
+ time.sleep(self.duration)
109
+
110
+ def _generate_sec_cpt_answers(self, sec: str) -> List[str]:
111
+ answers = []
112
+ if self.challenge_data.count <= 0:
113
+ return answers
114
+
115
+ difficulty = self.challenge_data.difficulty
116
+
117
+ while True:
118
+ answer = f"0.{os.urandom(8).hex()}"
119
+ hash_input = f"{sec}{self.challenge_data.timestamp}{self.challenge_data.nonce}{difficulty}{answer}"
120
+
121
+ output = 0
122
+ for byte in hashlib.sha256(hash_input.encode('ascii')).digest():
123
+ output = (output << 8) | byte
124
+ output %= difficulty
125
+
126
+ if output == 0:
127
+ difficulty += 1
128
+ answers.append(answer)
129
+
130
+ if len(answers) == self.challenge_data.count:
131
+ break
132
+ continue
133
+
130
134
  return answers
@@ -3,13 +3,14 @@ import re
3
3
  from typing import Optional
4
4
  from urllib.parse import urlencode
5
5
 
6
- # Matches the tag a challenge page uses to load the bundle from
7
- # ct.captcha-delivery.com, capturing the URL. The name in front of the version
8
- # is left open so it keeps matching whatever DataDome calls the bundle, e.g.
9
- # interstitial.1.33.0.202609141.js or captcha.1.34.0.202609141.js.
10
- _CHALLENGE_SCRIPT_REGEX = re.compile(
11
- r"""<script[^>]+src\s*=\s*["']([^"']*/[a-z_-]+\.\d+\.\d+\.\d+\.[^"']*\.js)["']"""
12
- )
6
+ # A challenge page loads its bundle with the only deferred <script> tag on the
7
+ # page, so the bundle is the src of the first tag carrying a defer attribute.
8
+ # The file name is not checked: DataDome renames the bundle freely, e.g.
9
+ # interstitial.1.36.0.js or captcha.build623.01-c-v1.38.0-2026-11-17-05h07.js.
10
+ # The c.js and i.js loaders are not deferred and never match.
11
+ _SCRIPT_TAG_REGEX = re.compile(r"<script\b([^>]*)>", re.IGNORECASE)
12
+ _DEFER_ATTR_REGEX = re.compile(r"(?:^|\s)defer(?:\s|=|/|$)", re.IGNORECASE)
13
+ _SRC_ATTR_REGEX = re.compile(r"""(?:^|\s)src\s*=\s*["']([^"']+)["']""", re.IGNORECASE)
13
14
 
14
15
 
15
16
  def parse_slider_device_check_link(src: str, datadome_cookie: str, referer: str) -> str:
@@ -133,8 +134,12 @@ def parse_challenge_script_url(html: str) -> Optional[str]:
133
134
  script=script,
134
135
  ))
135
136
  """
136
- match = _CHALLENGE_SCRIPT_REGEX.search(html)
137
- if match is None:
138
- return None
139
-
140
- return match.group(1)
137
+ for tag in _SCRIPT_TAG_REGEX.finditer(html):
138
+ attrs = tag.group(1)
139
+ if not _DEFER_ATTR_REGEX.search(attrs):
140
+ continue
141
+ src = _SRC_ATTR_REGEX.search(attrs)
142
+ if src is not None:
143
+ return src.group(1)
144
+
145
+ return None
@@ -5,7 +5,7 @@ the API adds later become new attributes rather than breaking changes.
5
5
  """
6
6
 
7
7
  from dataclasses import dataclass
8
- from typing import Dict, Optional
8
+ from typing import Any, Dict, List, Optional
9
9
 
10
10
  # The Accept-CH client hint headers for the device a payload was generated for,
11
11
  # keyed by lowercase header name, values ready to send verbatim (already
@@ -23,6 +23,7 @@ __all__ = [
23
23
  "Reese84Result", "UtmvcResult",
24
24
  "KasadaPayloadResult", "KasadaVersionResult", "KasadaPowResult", "BotIDHeaderResult", "DataDomeInterstitialResult",
25
25
  "DataDomeSliderResult", "DataDomeTagsResult", "TrustDecisionPayloadResult", "TrustDecisionSignatureResult",
26
+ "UsageResult", "UsagePlan",
26
27
  ]
27
28
 
28
29
 
@@ -106,6 +107,46 @@ class KasadaVersionResult:
106
107
  and in the x-kpsdk-v header."""
107
108
 
108
109
 
110
+ @dataclass
111
+ class UsagePlan:
112
+ """The quota of one plan in a UsageResult."""
113
+ product: str
114
+ """The product the plan covers, such as "akamai" or "datadome"."""
115
+ requests_used: int
116
+ """The number of requests used from the plan."""
117
+ requests_quota: int
118
+ """The number of requests the plan allows."""
119
+ requests_remaining: int
120
+ """requests_quota minus requests_used."""
121
+ expires_at: str
122
+ """When the plan expires, as an ISO 8601 date-time string."""
123
+
124
+
125
+ @dataclass
126
+ class UsageResult:
127
+ """Returned by get_usage."""
128
+ balance_euro: float
129
+ """The pay-as-you-go balance in euros."""
130
+ plans: List[UsagePlan]
131
+ """The plans of the API key, one per product."""
132
+
133
+ @classmethod
134
+ def from_dict(cls, data: Dict[str, Any]) -> "UsageResult":
135
+ return cls(
136
+ balance_euro=data["balanceEuro"],
137
+ plans=[
138
+ UsagePlan(
139
+ product=plan["product"],
140
+ requests_used=plan["requestsUsed"],
141
+ requests_quota=plan["requestsQuota"],
142
+ requests_remaining=plan["requestsRemaining"],
143
+ expires_at=plan["expiresAt"],
144
+ )
145
+ for plan in data["plans"]
146
+ ],
147
+ )
148
+
149
+
109
150
  @dataclass
110
151
  class KasadaPowResult:
111
152
  """Returned by generate_kasada_pow."""
@@ -14,7 +14,7 @@ from .trustdecision_input import PayloadInput, DecodeInput, SignatureInput
14
14
  from .results import (
15
15
  SensorResult, TelemetryResult, TelemetryParamsResult, PixelResult, SbsdResult, Reese84Result, UtmvcResult, KasadaPayloadResult,
16
16
  KasadaVersionResult, KasadaPowResult, BotIDHeaderResult, DataDomeInterstitialResult, DataDomeSliderResult,
17
- DataDomeTagsResult, TrustDecisionPayloadResult, TrustDecisionSignatureResult,
17
+ DataDomeTagsResult, TrustDecisionPayloadResult, TrustDecisionSignatureResult, UsageResult,
18
18
  )
19
19
  from .payloads import sensor_payload, telemetry_payload, telemetry_params_payload, sbsd_payload, pixel_payload, reese84_payload, utmvc_payload, \
20
20
  trustdecision_payload
@@ -180,6 +180,16 @@ class Session:
180
180
  data = self._post("https://kasada.hypersolutions.co/version", input_data.to_dict())
181
181
  return KasadaVersionResult(data["payload"])
182
182
 
183
+ def get_usage(self) -> UsageResult:
184
+ """
185
+ Returns the euro balance and the per-plan request quota of the session's API key, using the Hyper Solutions
186
+ API. It is not counted as usage.
187
+
188
+ Returns:
189
+ UsageResult: balance_euro and plans (one UsagePlan per product).
190
+ """
191
+ return UsageResult.from_dict(self._get("https://api.hypersolutions.co/usage"))
192
+
183
193
  def generate_botid_header(self, input_data: BotIDHeaderInput) -> BotIDHeaderResult:
184
194
  """
185
195
  Returns the x-is-human header value for Vercel BotID using the Hyper Solutions API.
@@ -350,6 +360,23 @@ class Session:
350
360
 
351
361
  return content
352
362
 
363
+ def _get(self, url: str) -> Dict[str, Any]:
364
+ """
365
+ Sends a GET without a body and returns the validated response body.
366
+
367
+ Args:
368
+ url (str): The endpoint URL
369
+
370
+ Returns:
371
+ Dict[str, Any]: The decoded response body
372
+ """
373
+ headers = self._build_headers()
374
+ headers.pop("Content-Type", None)
375
+ response = self.client.get(url, headers=headers)
376
+ response_data = json.loads(self._decompress_response(response))
377
+ validate_response(response_data, response.status_code)
378
+ return response_data
379
+
353
380
  def _post(self, url: str, input_data: Dict[str, Any]) -> Dict[str, Any]:
354
381
  """
355
382
  Sends a request and returns the validated response body.
@@ -14,7 +14,7 @@ from .trustdecision_input import PayloadInput, DecodeInput, SignatureInput
14
14
  from .results import (
15
15
  SensorResult, TelemetryResult, TelemetryParamsResult, PixelResult, SbsdResult, Reese84Result, UtmvcResult, KasadaPayloadResult,
16
16
  KasadaVersionResult, KasadaPowResult, BotIDHeaderResult, DataDomeInterstitialResult, DataDomeSliderResult,
17
- DataDomeTagsResult, TrustDecisionPayloadResult, TrustDecisionSignatureResult,
17
+ DataDomeTagsResult, TrustDecisionPayloadResult, TrustDecisionSignatureResult, UsageResult,
18
18
  )
19
19
  from .payloads import sensor_payload, telemetry_payload, telemetry_params_payload, sbsd_payload, pixel_payload, reese84_payload, utmvc_payload, \
20
20
  trustdecision_payload
@@ -188,6 +188,16 @@ class SessionAsync:
188
188
  data = await self._post("https://kasada.hypersolutions.co/version", input_data.to_dict())
189
189
  return KasadaVersionResult(data["payload"])
190
190
 
191
+ async def get_usage(self) -> UsageResult:
192
+ """
193
+ Returns the euro balance and the per-plan request quota of the session's API key, using the Hyper Solutions
194
+ API. It is not counted as usage.
195
+
196
+ Returns:
197
+ UsageResult: balance_euro and plans (one UsagePlan per product).
198
+ """
199
+ return UsageResult.from_dict(await self._get("https://api.hypersolutions.co/usage"))
200
+
191
201
  async def generate_botid_header(self, input_data: BotIDHeaderInput) -> BotIDHeaderResult:
192
202
  """
193
203
  Returns the x-is-human header value for Vercel BotID using the Hyper Solutions API.
@@ -358,6 +368,24 @@ class SessionAsync:
358
368
 
359
369
  return content
360
370
 
371
+ async def _get(self, url: str) -> Dict[str, Any]:
372
+ """
373
+ Sends a GET without a body and returns the validated response body.
374
+
375
+ Args:
376
+ url (str): The endpoint URL
377
+
378
+ Returns:
379
+ Dict[str, Any]: The decoded response body
380
+ """
381
+ await self.ensure_client()
382
+ headers = self._build_headers()
383
+ headers.pop("Content-Type", None)
384
+ response = await self.client.get(url, headers=headers)
385
+ response_data = json.loads(self._decompress_response(response))
386
+ validate_response(response_data, response.status_code)
387
+ return response_data
388
+
361
389
  async def _post(self, url: str, input_data: Dict[str, Any]) -> Dict[str, Any]:
362
390
  """
363
391
  Sends a request and returns the validated response body.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: hyper_sdk
3
- Version: 4.2.0
3
+ Version: 4.3.2
4
4
  Summary: Hyper Solutions Python SDK
5
5
  License: MIT License
6
6
 
@@ -146,6 +146,18 @@ session = Session(
146
146
  )
147
147
  ```
148
148
 
149
+ ### Checking Usage
150
+
151
+ `get_usage` returns the key's pay-as-you-go balance and the remaining requests of each plan. It is not counted as usage. `SessionAsync` has the same method.
152
+
153
+ ```python
154
+ usage = session.get_usage()
155
+
156
+ print(f"balance: €{usage.balance_euro}")
157
+ for plan in usage.plans:
158
+ print(f"{plan.product}: {plan.requests_remaining} of {plan.requests_quota} left, expires {plan.expires_at}")
159
+ ```
160
+
149
161
  ## 🛡️ Akamai Bot Manager
150
162
 
151
163
  Bypass **Akamai Bot Manager** protection with sensor data generation, cookie validation, and challenge solving.
@@ -31,7 +31,9 @@ hyper_sdk/kasada/__init__.py
31
31
  hyper_sdk/kasada/dv.py
32
32
  hyper_sdk/kasada/parse.py
33
33
  hyper_sdk/kasada/user_agent.py
34
+ tests/test_challenge_script_url.py
34
35
  tests/test_dv.py
35
36
  tests/test_results.py
36
37
  tests/test_script_hash.py
38
+ tests/test_sec_cpt.py
37
39
  tests/test_user_agent.py
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "hyper_sdk"
7
- version = "4.2.0"
7
+ version = "4.3.2"
8
8
  description = "Hyper Solutions Python SDK"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.7"
@@ -0,0 +1,68 @@
1
+ """Finds the deferred DataDome challenge bundle on a device check or captcha page."""
2
+
3
+ import unittest
4
+
5
+ from hyper_sdk.datadome import parse_challenge_script_url
6
+
7
+ BUILD_PREFIX_URL = "https://ct.captcha-delivery.com/captcha.build623.01-c-v1.38.0-2026-11-17-05h07.js"
8
+
9
+
10
+ class TestParseChallengeScriptUrl(unittest.TestCase):
11
+ def test_interstitial_with_build(self):
12
+ html = '<head><script defer src="https://ct.captcha-delivery.com/interstitial.1.33.0.202609141.js"></script></head>'
13
+ self.assertEqual(parse_challenge_script_url(html), "https://ct.captcha-delivery.com/interstitial.1.33.0.202609141.js")
14
+
15
+ def test_captcha_with_build(self):
16
+ html = '<script defer src="https://ct.captcha-delivery.com/captcha.1.34.0.202609141.js"></script>'
17
+ self.assertEqual(parse_challenge_script_url(html), "https://ct.captcha-delivery.com/captcha.1.34.0.202609141.js")
18
+
19
+ def test_interstitial_without_build(self):
20
+ html = '<head><script defer src="https://ct.captcha-delivery.com/interstitial.1.36.0.js"></script></head>'
21
+ self.assertEqual(parse_challenge_script_url(html), "https://ct.captcha-delivery.com/interstitial.1.36.0.js")
22
+
23
+ def test_single_quotes(self):
24
+ html = "<script defer src='https://ct.captcha-delivery.com/captcha.1.37.0.js'></script>"
25
+ self.assertEqual(parse_challenge_script_url(html), "https://ct.captcha-delivery.com/captcha.1.37.0.js")
26
+
27
+ def test_captcha_with_build_prefix(self):
28
+ html = f'<script defer src="{BUILD_PREFIX_URL}"></script>'
29
+ self.assertEqual(parse_challenge_script_url(html), BUILD_PREFIX_URL)
30
+
31
+ def test_build_prefix_after_inline_dd_object(self):
32
+ html = (
33
+ "<script data-cfasync=\"false\">var dd={'rt':'c'}</script>"
34
+ '<script data-cfasync="false" src="https://ct.captcha-delivery.com/c.js"></script>'
35
+ f'<script defer src="{BUILD_PREFIX_URL}"></script>'
36
+ )
37
+ self.assertEqual(parse_challenge_script_url(html), BUILD_PREFIX_URL)
38
+
39
+ def test_any_file_name(self):
40
+ html = '<script defer src="https://ct.captcha-delivery.com/interstitial-next.js"></script>'
41
+ self.assertEqual(parse_challenge_script_url(html), "https://ct.captcha-delivery.com/interstitial-next.js")
42
+
43
+ def test_defer_after_src(self):
44
+ html = f'<script src="{BUILD_PREFIX_URL}" defer></script>'
45
+ self.assertEqual(parse_challenge_script_url(html), BUILD_PREFIX_URL)
46
+
47
+ def test_first_deferred_tag_wins(self):
48
+ html = (
49
+ f'<script defer src="{BUILD_PREFIX_URL}"></script>'
50
+ '<script defer src="https://example.com/other.js"></script>'
51
+ )
52
+ self.assertEqual(parse_challenge_script_url(html), BUILD_PREFIX_URL)
53
+
54
+ def test_defer_in_src_is_not_the_attribute(self):
55
+ html = '<script src="https://example.com/defer.js"></script>'
56
+ self.assertIsNone(parse_challenge_script_url(html))
57
+
58
+ def test_versionless_loader(self):
59
+ html = '<script src="https://ct.captcha-delivery.com/i.js"></script>'
60
+ self.assertIsNone(parse_challenge_script_url(html))
61
+
62
+ def test_inlined_bundle(self):
63
+ html = "<script>var ddm = {};/* DataDome is a cyberfraud solution v1.33.0 */!function(){}()</script>"
64
+ self.assertIsNone(parse_challenge_script_url(html))
65
+
66
+
67
+ if __name__ == "__main__":
68
+ unittest.main()
@@ -155,6 +155,66 @@ class SyncResults(unittest.TestCase):
155
155
  s.generate_sensor_data(sensor_input())
156
156
 
157
157
 
158
+ USAGE_PLAN = {"expiresAt": "2027-07-31T00:00:00Z", "requestsUsed": 44235934, "requestsQuota": 9999999999,
159
+ "requestsRemaining": 9955764065, "product": "akamai"}
160
+
161
+
162
+ def usage_handler(status, body):
163
+ """A MockTransport handler for the body-less usage GET that records each request."""
164
+ def handler(request: httpx.Request) -> httpx.Response:
165
+ handler.requests.append(request)
166
+ return httpx.Response(status, json=body)
167
+
168
+ handler.requests = []
169
+ return handler
170
+
171
+
172
+ class Usage(unittest.TestCase):
173
+ def check_result(self, res):
174
+ self.assertEqual(res.balance_euro, 12.5)
175
+ self.assertEqual(len(res.plans), 1)
176
+ plan = res.plans[0]
177
+ self.assertEqual((plan.product, plan.requests_used, plan.requests_quota, plan.requests_remaining,
178
+ plan.expires_at),
179
+ ("akamai", 44235934, 9999999999, 9955764065, "2027-07-31T00:00:00Z"))
180
+
181
+ def check_request(self, handler):
182
+ self.assertEqual(len(handler.requests), 1)
183
+ req = handler.requests[0]
184
+ self.assertEqual((req.method, str(req.url)), ("GET", "https://api.hypersolutions.co/usage"))
185
+ self.assertEqual(req.content, b"")
186
+ self.assertEqual(req.headers["x-api-key"], "test-key")
187
+ self.assertNotIn("content-type", req.headers)
188
+
189
+ def test_sync(self):
190
+ handler = usage_handler(200, {"balanceEuro": 12.5, "plans": [USAGE_PLAN]})
191
+ s = Session("test-key", client=httpx.Client(transport=httpx.MockTransport(handler)))
192
+ self.check_result(s.get_usage())
193
+ self.check_request(handler)
194
+
195
+ s = Session("test-key", client=httpx.Client(transport=httpx.MockTransport(
196
+ usage_handler(403, {"error": "Invalid API key"}))))
197
+ with self.assertRaisesRegex(Exception, "Invalid API key"):
198
+ s.get_usage()
199
+
200
+ def test_async(self):
201
+ def run(handler):
202
+ async def go():
203
+ client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
204
+ async with SessionAsync("test-key", client=client) as s:
205
+ res = await s.get_usage()
206
+ await client.aclose()
207
+ return res
208
+
209
+ return asyncio.run(go())
210
+
211
+ handler = usage_handler(200, {"balanceEuro": 12.5, "plans": [USAGE_PLAN]})
212
+ self.check_result(run(handler))
213
+ self.check_request(handler)
214
+ with self.assertRaisesRegex(Exception, "Invalid API key"):
215
+ run(usage_handler(403, {"error": "Invalid API key"}))
216
+
217
+
158
218
  class AsyncResults(unittest.TestCase):
159
219
  def run_async(self, body, call):
160
220
  handler, sent = recorder(body)
@@ -0,0 +1,69 @@
1
+ """SEC-CPT challenge parsing and answer generation."""
2
+
3
+ import base64
4
+ import json
5
+ import unittest
6
+
7
+ from hyper_sdk.akamai import SecCptChallenge
8
+
9
+ CHALLENGE = {
10
+ "token": "tok",
11
+ "timestamp": 1713283747,
12
+ "nonce": "ebccdb479fcb92636fbc",
13
+ "difficulty": 1500,
14
+ "count": 3,
15
+ }
16
+
17
+
18
+ class ParseFromJsonTest(unittest.TestCase):
19
+ def test_reads_every_challenge_field(self):
20
+ payload = json.dumps({
21
+ **CHALLENGE,
22
+ "sec-cp-challenge": "true",
23
+ "provider": "adaptive",
24
+ "chlg_duration": 5,
25
+ "branding_url_content": "/_sec/cp_challenge/ak-challenge-4-3.htm",
26
+ })
27
+
28
+ challenge = SecCptChallenge.parse_from_json(payload)
29
+
30
+ self.assertEqual(challenge.duration, 5)
31
+ self.assertEqual(challenge.challenge_path, "/_sec/cp_challenge/ak-challenge-4-3.htm")
32
+ data = challenge.challenge_data
33
+ self.assertEqual(
34
+ (data.token, data.timestamp, data.nonce, data.difficulty, data.count),
35
+ ("tok", 1713283747, "ebccdb479fcb92636fbc", 1500, 3),
36
+ )
37
+
38
+ def test_payload_has_count_answers(self):
39
+ challenge = SecCptChallenge.parse_from_json(json.dumps(CHALLENGE))
40
+
41
+ payload = json.loads(challenge.generate_sec_cpt_payload("ABCDEF~3~xyz"))
42
+
43
+ self.assertEqual(payload["token"], "tok")
44
+ self.assertEqual(len(payload["answers"]), 3)
45
+
46
+ def test_missing_count_yields_no_answers(self):
47
+ challenge = SecCptChallenge.parse_from_json(json.dumps({k: v for k, v in CHALLENGE.items() if k != "count"}))
48
+
49
+ payload = json.loads(challenge.generate_sec_cpt_payload("ABCDEF~3~xyz"))
50
+
51
+ self.assertEqual(payload["answers"], [])
52
+
53
+
54
+ class ParseHtmlTest(unittest.TestCase):
55
+ def test_html_and_json_parse_to_the_same_challenge_data(self):
56
+ encoded = base64.b64encode(json.dumps(CHALLENGE).encode()).decode()
57
+ html = (
58
+ f'<iframe id="sec-cpt-if" provider="crypto" challenge="{encoded}" '
59
+ f'data-duration=5 src="/_sec/cp_challenge/ak-challenge-4-3.htm"></iframe>'
60
+ )
61
+
62
+ from_html = SecCptChallenge.parse(html).challenge_data
63
+ from_json = SecCptChallenge.parse_from_json(json.dumps(CHALLENGE)).challenge_data
64
+
65
+ self.assertEqual(vars(from_html), vars(from_json))
66
+
67
+
68
+ if __name__ == "__main__":
69
+ unittest.main()
File without changes
File without changes
File without changes
File without changes