hyper-sdk 4.2.0__tar.gz → 4.3.1__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 (40) hide show
  1. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/PKG-INFO +13 -1
  2. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/README.md +12 -0
  3. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/datadome/parse.py +5 -3
  4. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/results.py +42 -1
  5. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/session.py +28 -1
  6. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/session_async.py +29 -1
  7. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk.egg-info/PKG-INFO +13 -1
  8. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk.egg-info/SOURCES.txt +1 -0
  9. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/pyproject.toml +1 -1
  10. hyper_sdk-4.3.1/tests/test_challenge_script_url.py +35 -0
  11. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/tests/test_results.py +60 -0
  12. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/LICENSE +0 -0
  13. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/__init__.py +0 -0
  14. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/akamai/__init__.py +0 -0
  15. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/akamai/pixel.py +0 -0
  16. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/akamai/script_path.py +0 -0
  17. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/akamai/sec_cpt.py +0 -0
  18. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/akamai/stop_signal.py +0 -0
  19. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/akamai_input.py +0 -0
  20. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/datadome/__init__.py +0 -0
  21. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/datadome_input.py +0 -0
  22. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/incapsula/__init__.py +0 -0
  23. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/incapsula/dynamic.py +0 -0
  24. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/incapsula/utmvc.py +0 -0
  25. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/incapsula_input.py +0 -0
  26. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/kasada/__init__.py +0 -0
  27. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/kasada/dv.py +0 -0
  28. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/kasada/parse.py +0 -0
  29. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/kasada/user_agent.py +0 -0
  30. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/kasada_input.py +0 -0
  31. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/payloads.py +0 -0
  32. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/shared.py +0 -0
  33. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk/trustdecision_input.py +0 -0
  34. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk.egg-info/dependency_links.txt +0 -0
  35. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk.egg-info/requires.txt +0 -0
  36. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/hyper_sdk.egg-info/top_level.txt +0 -0
  37. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/setup.cfg +0 -0
  38. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/tests/test_dv.py +0 -0
  39. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/tests/test_script_hash.py +0 -0
  40. {hyper_sdk-4.2.0 → hyper_sdk-4.3.1}/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.1
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.
@@ -5,10 +5,12 @@ from urllib.parse import urlencode
5
5
 
6
6
  # Matches the tag a challenge page uses to load the bundle from
7
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.
8
+ # is left open so it keeps matching whatever DataDome calls the bundle, and the
9
+ # build segment after the version is optional: the bundle can be
10
+ # interstitial.1.33.0.202609141.js, captcha.1.34.0.202609141.js or
11
+ # interstitial.1.36.0.js.
10
12
  _CHALLENGE_SCRIPT_REGEX = re.compile(
11
- r"""<script[^>]+src\s*=\s*["']([^"']*/[a-z_-]+\.\d+\.\d+\.\d+\.[^"']*\.js)["']"""
13
+ r"""<script[^>]+src\s*=\s*["']([^"']*/[a-z_-]+\.\d+\.\d+\.\d+(?:\.[^"']*)?\.js)["']"""
12
14
  )
13
15
 
14
16
 
@@ -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.1
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,6 +31,7 @@ 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
@@ -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.1"
8
8
  description = "Hyper Solutions Python SDK"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.7"
@@ -0,0 +1,35 @@
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
+
8
+ class TestParseChallengeScriptUrl(unittest.TestCase):
9
+ def test_interstitial_with_build(self):
10
+ html = '<head><script defer src="https://ct.captcha-delivery.com/interstitial.1.33.0.202609141.js"></script></head>'
11
+ self.assertEqual(parse_challenge_script_url(html), "https://ct.captcha-delivery.com/interstitial.1.33.0.202609141.js")
12
+
13
+ def test_captcha_with_build(self):
14
+ html = '<script defer src="https://ct.captcha-delivery.com/captcha.1.34.0.202609141.js"></script>'
15
+ self.assertEqual(parse_challenge_script_url(html), "https://ct.captcha-delivery.com/captcha.1.34.0.202609141.js")
16
+
17
+ def test_interstitial_without_build(self):
18
+ html = '<head><script defer src="https://ct.captcha-delivery.com/interstitial.1.36.0.js"></script></head>'
19
+ self.assertEqual(parse_challenge_script_url(html), "https://ct.captcha-delivery.com/interstitial.1.36.0.js")
20
+
21
+ def test_single_quotes(self):
22
+ html = "<script src='https://ct.captcha-delivery.com/captcha.1.37.0.js'></script>"
23
+ self.assertEqual(parse_challenge_script_url(html), "https://ct.captcha-delivery.com/captcha.1.37.0.js")
24
+
25
+ def test_versionless_loader(self):
26
+ html = '<script src="https://ct.captcha-delivery.com/i.js"></script>'
27
+ self.assertIsNone(parse_challenge_script_url(html))
28
+
29
+ def test_inlined_bundle(self):
30
+ html = "<script>var ddm = {};/* DataDome is a cyberfraud solution v1.33.0 */!function(){}()</script>"
31
+ self.assertIsNone(parse_challenge_script_url(html))
32
+
33
+
34
+ if __name__ == "__main__":
35
+ 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)
File without changes
File without changes
File without changes
File without changes