hyper-sdk 4.0.0__tar.gz → 4.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 (37) hide show
  1. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/PKG-INFO +1 -1
  2. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/kasada_input.py +15 -0
  3. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/results.py +9 -1
  4. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/session.py +63 -12
  5. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/session_async.py +63 -12
  6. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/shared.py +31 -2
  7. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk.egg-info/PKG-INFO +1 -1
  8. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk.egg-info/SOURCES.txt +1 -0
  9. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/pyproject.toml +1 -1
  10. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/tests/test_results.py +26 -1
  11. hyper_sdk-4.1.0/tests/test_script_hash.py +248 -0
  12. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/LICENSE +0 -0
  13. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/README.md +0 -0
  14. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/__init__.py +0 -0
  15. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/akamai/__init__.py +0 -0
  16. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/akamai/pixel.py +0 -0
  17. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/akamai/script_path.py +0 -0
  18. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/akamai/sec_cpt.py +0 -0
  19. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/akamai/stop_signal.py +0 -0
  20. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/akamai_input.py +0 -0
  21. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/datadome/__init__.py +0 -0
  22. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/datadome/parse.py +0 -0
  23. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/datadome_input.py +0 -0
  24. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/incapsula/__init__.py +0 -0
  25. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/incapsula/dynamic.py +0 -0
  26. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/incapsula/utmvc.py +0 -0
  27. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/incapsula_input.py +0 -0
  28. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/kasada/__init__.py +0 -0
  29. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/kasada/parse.py +0 -0
  30. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/kasada/user_agent.py +0 -0
  31. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/payloads.py +0 -0
  32. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk/trustdecision_input.py +0 -0
  33. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk.egg-info/dependency_links.txt +0 -0
  34. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk.egg-info/requires.txt +0 -0
  35. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/hyper_sdk.egg-info/top_level.txt +0 -0
  36. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/setup.cfg +0 -0
  37. {hyper_sdk-4.0.0 → hyper_sdk-4.1.0}/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.0.0
3
+ Version: 4.1.0
4
4
  Summary: Hyper Solutions Python SDK
5
5
  License: MIT License
6
6
 
@@ -53,6 +53,21 @@ class KasadaPayloadInput:
53
53
  result["strict"] = True
54
54
  return result
55
55
 
56
+ class KasadaVersionInput:
57
+ def __init__(self, page_url: str, script: str):
58
+ # PageUrl is the URL of the page that loaded p.js
59
+ self.page_url = page_url
60
+
61
+ # Script is the p.js script
62
+ self.script = script
63
+
64
+ def to_dict(self):
65
+ return {
66
+ "pageUrl": self.page_url,
67
+ "script": self.script,
68
+ }
69
+
70
+
56
71
  class BotIDHeaderInput:
57
72
  def __init__(self, script: str, user_agent: str, ip: str, accept_language: str):
58
73
  # Script is the c.js script retrieved from the BotID script endpoint
@@ -21,7 +21,7 @@ ClientHints = Optional[Dict[str, str]]
21
21
  __all__ = [
22
22
  "ClientHints", "SensorResult", "TelemetryResult", "TelemetryParamsResult", "PixelResult", "SbsdResult",
23
23
  "Reese84Result", "UtmvcResult",
24
- "KasadaPayloadResult", "KasadaPowResult", "BotIDHeaderResult", "DataDomeInterstitialResult",
24
+ "KasadaPayloadResult", "KasadaVersionResult", "KasadaPowResult", "BotIDHeaderResult", "DataDomeInterstitialResult",
25
25
  "DataDomeSliderResult", "DataDomeTagsResult", "TrustDecisionPayloadResult", "TrustDecisionSignatureResult",
26
26
  ]
27
27
 
@@ -98,6 +98,14 @@ class KasadaPayloadResult:
98
98
  """Accept-CH headers; unlike headers, send only the ones the site asked for."""
99
99
 
100
100
 
101
+ @dataclass
102
+ class KasadaVersionResult:
103
+ """Returned by get_kasada_version."""
104
+ version: str
105
+ """The x-kpsdk-v value, such as "j-1.2.797". Send it verbatim on the /fp request
106
+ and in the x-kpsdk-v header."""
107
+
108
+
101
109
  @dataclass
102
110
  class KasadaPowResult:
103
111
  """Returned by generate_kasada_pow."""
@@ -5,15 +5,15 @@ import httpx
5
5
  import json
6
6
  import gzip
7
7
 
8
- from .shared import generate_signature, build_headers, validate_response
8
+ from .shared import generate_signature, build_headers, validate_response, with_script_hash, is_script_required
9
9
  from .akamai_input import SensorInput, PixelInput, SbsdInput, TelemetryInput, TelemetryParamsInput
10
- from .kasada_input import KasadaPowInput, KasadaPayloadInput, BotIDHeaderInput
10
+ from .kasada_input import KasadaPowInput, KasadaPayloadInput, KasadaVersionInput, BotIDHeaderInput
11
11
  from .datadome_input import DataDomeSliderInput, DataDomeInterstitialInput, DataDomeTagsInput
12
12
  from .incapsula_input import UtmvcInput, ReeseInput
13
13
  from .trustdecision_input import PayloadInput, DecodeInput, SignatureInput
14
14
  from .results import (
15
15
  SensorResult, TelemetryResult, TelemetryParamsResult, PixelResult, SbsdResult, Reese84Result, UtmvcResult, KasadaPayloadResult,
16
- KasadaPowResult, BotIDHeaderResult, DataDomeInterstitialResult, DataDomeSliderResult,
16
+ KasadaVersionResult, KasadaPowResult, BotIDHeaderResult, DataDomeInterstitialResult, DataDomeSliderResult,
17
17
  DataDomeTagsResult, TrustDecisionPayloadResult, TrustDecisionSignatureResult,
18
18
  )
19
19
  from .payloads import sensor_payload, telemetry_payload, telemetry_params_payload, sbsd_payload, pixel_payload, reese84_payload, utmvc_payload, \
@@ -54,7 +54,7 @@ class Session:
54
54
  Returns:
55
55
  SensorResult: payload (sensor data), context (for the next sensor request) and client_hints.
56
56
  """
57
- data = self._post("https://akm.hypersolutions.co/v2/sensor", sensor_payload(input_data))
57
+ data = self._post_script("https://akm.hypersolutions.co/v2/sensor", sensor_payload(input_data))
58
58
  return SensorResult(data["payload"], data.get("context", ""), data.get("headers"))
59
59
 
60
60
  def generate_telemetry(self, input_data: TelemetryInput) -> TelemetryResult:
@@ -68,7 +68,7 @@ class Session:
68
68
  Returns:
69
69
  TelemetryResult: header (the header value), context (for the next telemetry request) and client_hints.
70
70
  """
71
- data = self._post("https://akm.hypersolutions.co/v1/telemetry", telemetry_payload(input_data))
71
+ data = self._post_script("https://akm.hypersolutions.co/v1/telemetry", telemetry_payload(input_data))
72
72
  return TelemetryResult(data["payload"], data.get("context", ""), data.get("headers"))
73
73
 
74
74
  def get_telemetry_params(self, input_data: TelemetryParamsInput) -> TelemetryParamsResult:
@@ -82,7 +82,7 @@ class Session:
82
82
  Returns:
83
83
  TelemetryParamsResult: path (the get_params path) and context.
84
84
  """
85
- data = self._post("https://akm.hypersolutions.co/v1/telemetry/params", telemetry_params_payload(input_data))
85
+ data = self._post_script("https://akm.hypersolutions.co/v1/telemetry/params", telemetry_params_payload(input_data))
86
86
  return TelemetryParamsResult(data["payload"], data.get("context", ""))
87
87
 
88
88
  def generate_sbsd_data(self, input_data: SbsdInput) -> SbsdResult:
@@ -95,7 +95,7 @@ class Session:
95
95
  Returns:
96
96
  SbsdResult: payload (sbsd data), context (for the next sbsd request) and client_hints.
97
97
  """
98
- data = self._post("https://akm.hypersolutions.co/sbsd", sbsd_payload(input_data))
98
+ data = self._post_script("https://akm.hypersolutions.co/sbsd", sbsd_payload(input_data))
99
99
  return SbsdResult(data["payload"], data.get("context", ""), data.get("headers"))
100
100
 
101
101
  def generate_pixel_data(self, input_data: PixelInput) -> PixelResult:
@@ -121,7 +121,7 @@ class Session:
121
121
  Returns:
122
122
  Reese84Result: payload (sensor data) and client_hints (None for Safari user agents).
123
123
  """
124
- data = self._post("https://incapsula.hypersolutions.co/reese84", reese84_payload(input_data))
124
+ data = self._post_script("https://incapsula.hypersolutions.co/reese84", reese84_payload(input_data))
125
125
  return Reese84Result(data["payload"], data.get("headers"))
126
126
 
127
127
  def generate_utmvc_cookie(self, input_data: UtmvcInput) -> UtmvcResult:
@@ -166,6 +166,20 @@ class Session:
166
166
  data = self._post("https://kasada.hypersolutions.co/payload", input_data.to_dict())
167
167
  return KasadaPayloadResult(data["payload"], data["headers"], data.get("clientHints"))
168
168
 
169
+ def get_kasada_version(self, input_data: KasadaVersionInput) -> KasadaVersionResult:
170
+ """
171
+ Returns the x-kpsdk-v value of a site's p.js, sent verbatim on the /fp request and in the x-kpsdk-v header,
172
+ using the Hyper Solutions API. It is a helper and is not counted as usage.
173
+
174
+ Args:
175
+ input_data (KasadaVersionInput): An instance of KasadaVersionInput with the page url and the p.js script.
176
+
177
+ Returns:
178
+ KasadaVersionResult: version (the x-kpsdk-v value).
179
+ """
180
+ data = self._post("https://kasada.hypersolutions.co/version", input_data.to_dict())
181
+ return KasadaVersionResult(data["payload"])
182
+
169
183
  def generate_botid_header(self, input_data: BotIDHeaderInput) -> BotIDHeaderResult:
170
184
  """
171
185
  Returns the x-is-human header value for Vercel BotID using the Hyper Solutions API.
@@ -190,7 +204,7 @@ class Session:
190
204
  Returns:
191
205
  DataDomeInterstitialResult: payload (to post to /interstitial/) and client_hints.
192
206
  """
193
- data = self._post("https://datadome.hypersolutions.co/interstitial", input_data.to_dict())
207
+ data = self._post_script("https://datadome.hypersolutions.co/interstitial", input_data.to_dict())
194
208
  return DataDomeInterstitialResult(data["payload"], data.get("headers"))
195
209
 
196
210
  def generate_slider_payload(self, input_data: DataDomeSliderInput) -> DataDomeSliderResult:
@@ -203,7 +217,7 @@ class Session:
203
217
  Returns:
204
218
  DataDomeSliderResult: payload (the URL to GET for a solved datadome cookie) and client_hints.
205
219
  """
206
- data = self._post("https://datadome.hypersolutions.co/slider", input_data.to_dict())
220
+ data = self._post_script("https://datadome.hypersolutions.co/slider", input_data.to_dict())
207
221
  return DataDomeSliderResult(data["payload"], data.get("headers"))
208
222
 
209
223
  def generate_tags_payload(self, input_data: DataDomeTagsInput) -> DataDomeTagsResult:
@@ -347,6 +361,44 @@ class Session:
347
361
  Returns:
348
362
  Dict[str, Any]: The decoded response body
349
363
  """
364
+ response_data, status_code = self._send(url, input_data)
365
+ validate_response(response_data, status_code)
366
+ return response_data
367
+
368
+ def _post_script(self, url: str, input_data: Dict[str, Any]) -> Dict[str, Any]:
369
+ """
370
+ Sends a request that carries a challenge script with only the script's hash in place of the script. The API
371
+ answers 422 script_required only for a script no client has sent yet, and the request is then sent once more
372
+ with the script, which the API stores for every later request.
373
+
374
+ Args:
375
+ url (str): The endpoint URL
376
+ input_data (Dict[str, Any]): The request data, script included
377
+
378
+ Returns:
379
+ Dict[str, Any]: The decoded response body
380
+ """
381
+ hashed = with_script_hash(input_data)
382
+ if hashed is None:
383
+ return self._post(url, input_data)
384
+
385
+ response_data, status_code = self._send(url, hashed)
386
+ if is_script_required(response_data, status_code):
387
+ return self._post(url, input_data)
388
+ validate_response(response_data, status_code)
389
+ return response_data
390
+
391
+ def _send(self, url: str, input_data: Dict[str, Any]) -> Tuple[Any, int]:
392
+ """
393
+ Sends a request and returns the decoded response body and the status code.
394
+
395
+ Args:
396
+ url (str): The endpoint URL
397
+ input_data (Dict[str, Any]): The request data
398
+
399
+ Returns:
400
+ Tuple[Any, int]: The decoded response body and the HTTP status code
401
+ """
350
402
  headers = self._build_headers()
351
403
  payload = json.dumps(input_data).encode('utf-8')
352
404
 
@@ -360,5 +412,4 @@ class Session:
360
412
  # Decompress response if needed
361
413
  response_content = self._decompress_response(response)
362
414
  response_data = json.loads(response_content)
363
- validate_response(response_data, response.status_code)
364
- return response_data
415
+ return response_data, response.status_code
@@ -5,15 +5,15 @@ import httpx
5
5
  import json
6
6
  import gzip
7
7
 
8
- from .shared import generate_signature, build_headers, validate_response
8
+ from .shared import generate_signature, build_headers, validate_response, with_script_hash, is_script_required
9
9
  from .akamai_input import SensorInput, PixelInput, SbsdInput, TelemetryInput, TelemetryParamsInput
10
- from .kasada_input import KasadaPowInput, KasadaPayloadInput, BotIDHeaderInput
10
+ from .kasada_input import KasadaPowInput, KasadaPayloadInput, KasadaVersionInput, BotIDHeaderInput
11
11
  from .datadome_input import DataDomeSliderInput, DataDomeInterstitialInput, DataDomeTagsInput
12
12
  from .incapsula_input import UtmvcInput, ReeseInput
13
13
  from .trustdecision_input import PayloadInput, DecodeInput, SignatureInput
14
14
  from .results import (
15
15
  SensorResult, TelemetryResult, TelemetryParamsResult, PixelResult, SbsdResult, Reese84Result, UtmvcResult, KasadaPayloadResult,
16
- KasadaPowResult, BotIDHeaderResult, DataDomeInterstitialResult, DataDomeSliderResult,
16
+ KasadaVersionResult, KasadaPowResult, BotIDHeaderResult, DataDomeInterstitialResult, DataDomeSliderResult,
17
17
  DataDomeTagsResult, TrustDecisionPayloadResult, TrustDecisionSignatureResult,
18
18
  )
19
19
  from .payloads import sensor_payload, telemetry_payload, telemetry_params_payload, sbsd_payload, pixel_payload, reese84_payload, utmvc_payload, \
@@ -62,7 +62,7 @@ class SessionAsync:
62
62
  Returns:
63
63
  SensorResult: payload (sensor data), context (for the next sensor request) and client_hints.
64
64
  """
65
- data = await self._post("https://akm.hypersolutions.co/v2/sensor", sensor_payload(input_data))
65
+ data = await self._post_script("https://akm.hypersolutions.co/v2/sensor", sensor_payload(input_data))
66
66
  return SensorResult(data["payload"], data.get("context", ""), data.get("headers"))
67
67
 
68
68
  async def generate_telemetry(self, input_data: TelemetryInput) -> TelemetryResult:
@@ -76,7 +76,7 @@ class SessionAsync:
76
76
  Returns:
77
77
  TelemetryResult: header (the header value), context (for the next telemetry request) and client_hints.
78
78
  """
79
- data = await self._post("https://akm.hypersolutions.co/v1/telemetry", telemetry_payload(input_data))
79
+ data = await self._post_script("https://akm.hypersolutions.co/v1/telemetry", telemetry_payload(input_data))
80
80
  return TelemetryResult(data["payload"], data.get("context", ""), data.get("headers"))
81
81
 
82
82
  async def get_telemetry_params(self, input_data: TelemetryParamsInput) -> TelemetryParamsResult:
@@ -90,7 +90,7 @@ class SessionAsync:
90
90
  Returns:
91
91
  TelemetryParamsResult: path (the get_params path) and context.
92
92
  """
93
- data = await self._post("https://akm.hypersolutions.co/v1/telemetry/params", telemetry_params_payload(input_data))
93
+ data = await self._post_script("https://akm.hypersolutions.co/v1/telemetry/params", telemetry_params_payload(input_data))
94
94
  return TelemetryParamsResult(data["payload"], data.get("context", ""))
95
95
 
96
96
  async def generate_sbsd_data(self, input_data: SbsdInput) -> SbsdResult:
@@ -103,7 +103,7 @@ class SessionAsync:
103
103
  Returns:
104
104
  SbsdResult: payload (sbsd data), context (for the next sbsd request) and client_hints.
105
105
  """
106
- data = await self._post("https://akm.hypersolutions.co/sbsd", sbsd_payload(input_data))
106
+ data = await self._post_script("https://akm.hypersolutions.co/sbsd", sbsd_payload(input_data))
107
107
  return SbsdResult(data["payload"], data.get("context", ""), data.get("headers"))
108
108
 
109
109
  async def generate_pixel_data(self, input_data: PixelInput) -> PixelResult:
@@ -129,7 +129,7 @@ class SessionAsync:
129
129
  Returns:
130
130
  Reese84Result: payload (sensor data) and client_hints (None for Safari user agents).
131
131
  """
132
- data = await self._post("https://incapsula.hypersolutions.co/reese84", reese84_payload(input_data))
132
+ data = await self._post_script("https://incapsula.hypersolutions.co/reese84", reese84_payload(input_data))
133
133
  return Reese84Result(data["payload"], data.get("headers"))
134
134
 
135
135
  async def generate_utmvc_cookie(self, input_data: UtmvcInput) -> UtmvcResult:
@@ -174,6 +174,20 @@ class SessionAsync:
174
174
  data = await self._post("https://kasada.hypersolutions.co/payload", input_data.to_dict())
175
175
  return KasadaPayloadResult(data["payload"], data["headers"], data.get("clientHints"))
176
176
 
177
+ async def get_kasada_version(self, input_data: KasadaVersionInput) -> KasadaVersionResult:
178
+ """
179
+ Returns the x-kpsdk-v value of a site's p.js, sent verbatim on the /fp request and in the x-kpsdk-v header,
180
+ using the Hyper Solutions API. It is a helper and is not counted as usage.
181
+
182
+ Args:
183
+ input_data (KasadaVersionInput): An instance of KasadaVersionInput with the page url and the p.js script.
184
+
185
+ Returns:
186
+ KasadaVersionResult: version (the x-kpsdk-v value).
187
+ """
188
+ data = await self._post("https://kasada.hypersolutions.co/version", input_data.to_dict())
189
+ return KasadaVersionResult(data["payload"])
190
+
177
191
  async def generate_botid_header(self, input_data: BotIDHeaderInput) -> BotIDHeaderResult:
178
192
  """
179
193
  Returns the x-is-human header value for Vercel BotID using the Hyper Solutions API.
@@ -198,7 +212,7 @@ class SessionAsync:
198
212
  Returns:
199
213
  DataDomeInterstitialResult: payload (to post to /interstitial/) and client_hints.
200
214
  """
201
- data = await self._post("https://datadome.hypersolutions.co/interstitial", input_data.to_dict())
215
+ data = await self._post_script("https://datadome.hypersolutions.co/interstitial", input_data.to_dict())
202
216
  return DataDomeInterstitialResult(data["payload"], data.get("headers"))
203
217
 
204
218
  async def generate_slider_payload(self, input_data: DataDomeSliderInput) -> DataDomeSliderResult:
@@ -211,7 +225,7 @@ class SessionAsync:
211
225
  Returns:
212
226
  DataDomeSliderResult: payload (the URL to GET for a solved datadome cookie) and client_hints.
213
227
  """
214
- data = await self._post("https://datadome.hypersolutions.co/slider", input_data.to_dict())
228
+ data = await self._post_script("https://datadome.hypersolutions.co/slider", input_data.to_dict())
215
229
  return DataDomeSliderResult(data["payload"], data.get("headers"))
216
230
 
217
231
  async def generate_tags_payload(self, input_data: DataDomeTagsInput) -> DataDomeTagsResult:
@@ -355,6 +369,44 @@ class SessionAsync:
355
369
  Returns:
356
370
  Dict[str, Any]: The decoded response body
357
371
  """
372
+ response_data, status_code = await self._send(url, input_data)
373
+ validate_response(response_data, status_code)
374
+ return response_data
375
+
376
+ async def _post_script(self, url: str, input_data: Dict[str, Any]) -> Dict[str, Any]:
377
+ """
378
+ Sends a request that carries a challenge script with only the script's hash in place of the script. The API
379
+ answers 422 script_required only for a script no client has sent yet, and the request is then sent once more
380
+ with the script, which the API stores for every later request.
381
+
382
+ Args:
383
+ url (str): The endpoint URL
384
+ input_data (Dict[str, Any]): The request data, script included
385
+
386
+ Returns:
387
+ Dict[str, Any]: The decoded response body
388
+ """
389
+ hashed = with_script_hash(input_data)
390
+ if hashed is None:
391
+ return await self._post(url, input_data)
392
+
393
+ response_data, status_code = await self._send(url, hashed)
394
+ if is_script_required(response_data, status_code):
395
+ return await self._post(url, input_data)
396
+ validate_response(response_data, status_code)
397
+ return response_data
398
+
399
+ async def _send(self, url: str, input_data: Dict[str, Any]) -> Tuple[Any, int]:
400
+ """
401
+ Sends a request and returns the decoded response body and the status code.
402
+
403
+ Args:
404
+ url (str): The endpoint URL
405
+ input_data (Dict[str, Any]): The request data
406
+
407
+ Returns:
408
+ Tuple[Any, int]: The decoded response body and the HTTP status code
409
+ """
358
410
  await self.ensure_client()
359
411
  headers = self._build_headers()
360
412
  payload = json.dumps(input_data).encode('utf-8')
@@ -369,5 +421,4 @@ class SessionAsync:
369
421
  # Decompress response if needed
370
422
  response_content = self._decompress_response(response)
371
423
  response_data = json.loads(response_content)
372
- validate_response(response_data, response.status_code)
373
- return response_data
424
+ return response_data, response.status_code
@@ -1,7 +1,8 @@
1
1
  """Shared utility functions for both sync and async Session classes."""
2
2
 
3
- from typing import Dict
3
+ from typing import Any, Dict, Optional
4
4
  from datetime import datetime, timedelta, timezone
5
+ import hashlib
5
6
  import jwt
6
7
 
7
8
 
@@ -75,4 +76,32 @@ def validate_response(response_data: dict, status_code: int) -> None:
75
76
  raise Exception(f"API returned with error: {response_data['error']}")
76
77
 
77
78
  if status_code != 200:
78
- raise Exception(f"API returned with status code: {status_code}")
79
+ raise Exception(f"API returned with status code: {status_code}")
80
+
81
+
82
+ def script_hash(script: str) -> str:
83
+ """
84
+ Returns the hash the API identifies a challenge script by: the lowercase hex sha256 of the script's UTF-8 bytes,
85
+ exactly as the site served it.
86
+ """
87
+ return hashlib.sha256(script.encode('utf-8')).hexdigest()
88
+
89
+
90
+ def with_script_hash(payload: Dict[str, Any]) -> Optional[Dict[str, Any]]:
91
+ """
92
+ Returns a copy of payload with its script replaced by a "scriptHash" field, or None when payload has no script.
93
+ The hash stays out of the public input types, so callers always pass the script.
94
+ """
95
+ script = payload.get('script')
96
+ if not script:
97
+ return None
98
+ hashed = {key: value for key, value in payload.items() if key != 'script'}
99
+ hashed['scriptHash'] = script_hash(script)
100
+ return hashed
101
+
102
+
103
+ def is_script_required(response_data: Any, status_code: int) -> bool:
104
+ """
105
+ Reports whether the API answered that it has not seen a script hash yet and needs the script itself.
106
+ """
107
+ return status_code == 422 and isinstance(response_data, dict) and response_data.get('error') == 'script_required'
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: hyper_sdk
3
- Version: 4.0.0
3
+ Version: 4.1.0
4
4
  Summary: Hyper Solutions Python SDK
5
5
  License: MIT License
6
6
 
@@ -31,4 +31,5 @@ hyper_sdk/kasada/__init__.py
31
31
  hyper_sdk/kasada/parse.py
32
32
  hyper_sdk/kasada/user_agent.py
33
33
  tests/test_results.py
34
+ tests/test_script_hash.py
34
35
  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.0.0"
7
+ version = "4.1.0"
8
8
  description = "Hyper Solutions Python SDK"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.7"
@@ -1,6 +1,7 @@
1
1
  """Runs the real Session / SessionAsync methods against canned API responses."""
2
2
 
3
3
  import asyncio
4
+ import hashlib
4
5
  import json
5
6
  import unittest
6
7
 
@@ -8,6 +9,7 @@ import httpx
8
9
 
9
10
  from hyper_sdk import (
10
11
  Session, SessionAsync, SensorInput, SbsdInput, TelemetryInput, TelemetryParamsInput, ReeseInput, KasadaPayloadInput,
12
+ KasadaVersionInput,
11
13
  DataDomeSliderInput, DataDomeInterstitialInput, DataDomeTagsInput,
12
14
  )
13
15
 
@@ -129,9 +131,24 @@ class SyncResults(unittest.TestCase):
129
131
  s = Session("test-key", client=httpx.Client(transport=httpx.MockTransport(handler)))
130
132
  res = s.get_telemetry_params(TelemetryParamsInput(page_url="https://example.com/", script="s"))
131
133
  self.assertEqual(handler.urls[0], "https://akm.hypersolutions.co/v1/telemetry/params")
132
- self.assertEqual(sent[0], {"pageUrl": "https://example.com/", "script": "s", "context": ""})
134
+ # a script goes out as its hash; this canned API accepts the hash
135
+ self.assertEqual(sent[0], {"pageUrl": "https://example.com/", "context": "",
136
+ "scriptHash": hashlib.sha256(b"s").hexdigest()})
133
137
  self.assertEqual((res.path, res.context), ("/_bm/get_params?type=web-jsto&v=aN+c/9=", "c"))
134
138
 
139
+ def test_kasada_version(self):
140
+ # the script goes out as-is, never as a hash
141
+ handler, sent = recorder({"payload": "j-1.2.797"})
142
+ s = Session("test-key", client=httpx.Client(transport=httpx.MockTransport(handler)))
143
+ res = s.get_kasada_version(KasadaVersionInput(page_url="https://example.com/", script="p.js body"))
144
+ self.assertEqual(handler.urls, ["https://kasada.hypersolutions.co/version"])
145
+ self.assertEqual(sent, [{"pageUrl": "https://example.com/", "script": "p.js body"}])
146
+ self.assertEqual(res.version, "j-1.2.797")
147
+
148
+ s, _ = self.session({"error": "invalid script"})
149
+ with self.assertRaisesRegex(Exception, "invalid script"):
150
+ s.get_kasada_version(KasadaVersionInput(page_url="https://example.com/", script="p.js body"))
151
+
135
152
  def test_api_error_still_raises(self):
136
153
  s, _ = self.session({"error": "boom"})
137
154
  with self.assertRaises(Exception):
@@ -166,6 +183,14 @@ class AsyncResults(unittest.TestCase):
166
183
  script="s")))
167
184
  self.assertEqual((res.path, res.context), ("/_bm/get_params?type=web-jsto&v=x", "c"))
168
185
 
186
+ def test_kasada_version(self):
187
+ version_input = KasadaVersionInput(page_url="https://example.com/", script="p.js body")
188
+ res, sent = self.run_async({"payload": "j-1.2.797"}, lambda s: s.get_kasada_version(version_input))
189
+ self.assertEqual(sent, [{"pageUrl": "https://example.com/", "script": "p.js body"}])
190
+ self.assertEqual(res.version, "j-1.2.797")
191
+ with self.assertRaisesRegex(Exception, "invalid script"):
192
+ self.run_async({"error": "invalid script"}, lambda s: s.get_kasada_version(version_input))
193
+
169
194
  def test_kasada_payload_and_strict(self):
170
195
  res, sent = self.run_async(KASADA_BODY, lambda s: s.generate_kasada_payload(kasada_input(strict=True)))
171
196
  self.assertEqual(res.headers["x-kpsdk-ct"], "ct")
@@ -0,0 +1,248 @@
1
+ """Sends challenge scripts by hash, falling back to the script when the API has not seen the hash."""
2
+
3
+ import asyncio
4
+ import copy
5
+ import hashlib
6
+ import json
7
+ import unittest
8
+
9
+ import httpx
10
+
11
+ from hyper_sdk import (
12
+ Session, SessionAsync, SensorInput, SbsdInput, TelemetryInput, TelemetryParamsInput, ReeseInput, DataDomeSliderInput, DataDomeInterstitialInput,
13
+ )
14
+
15
+ SCRIPT = "(function(){var a='é';return a})();"
16
+ SCRIPT_HASH = hashlib.sha256(SCRIPT.encode("utf-8")).hexdigest()
17
+ OK = {"payload": "p", "context": "c"}
18
+
19
+
20
+ class FakeAPI:
21
+ """A MockTransport handler that knows the scripts it was sent, the way the API stores them by hash."""
22
+
23
+ def __init__(self, known=(), after_script=None):
24
+ self.known = set(known)
25
+ # after_script, when set, is the (status, body) answered to a request that carries the script
26
+ self.after_script = after_script
27
+ self.sent = []
28
+
29
+ def __call__(self, request: httpx.Request) -> httpx.Response:
30
+ body = json.loads(request.content)
31
+ self.sent.append(body)
32
+ if "script" in body and "scriptHash" in body:
33
+ return httpx.Response(400, json={"error": "script and scriptHash are mutually exclusive"})
34
+ if body.get("script"):
35
+ self.known.add(hashlib.sha256(body["script"].encode("utf-8")).hexdigest())
36
+ if self.after_script is not None:
37
+ status, answer = self.after_script
38
+ return httpx.Response(status, json=answer)
39
+ elif "scriptHash" in body and body["scriptHash"] not in self.known:
40
+ return httpx.Response(422, json={"error": "script_required"})
41
+ return httpx.Response(200, json=OK)
42
+
43
+
44
+ def sensor_input(script=SCRIPT, context=""):
45
+ return SensorInput(abck="abck", bmsz="bmsz", version="3", page_url="https://example.com/", user_agent="ua",
46
+ ip="1.2.3.4", accept_language="en-US", context=context, script=script,
47
+ script_url="https://example.com/s.js")
48
+
49
+
50
+ def sbsd_input(script=SCRIPT, context=""):
51
+ return SbsdInput(user_agent="ua", uuid="uuid", page_url="https://example.com/", o_cookie="o", script=script,
52
+ accept_language="en-US", ip="1.2.3.4", context=context)
53
+
54
+
55
+ def telemetry_input(script=SCRIPT):
56
+ return TelemetryInput(abck="abck", bmsz="bmsz", page_url="https://example.com/", user_agent="ua", ip="1.2.3.4",
57
+ accept_language="en-US", context="", script=script, script_url="https://example.com/s.js",
58
+ j="AAQ")
59
+
60
+
61
+ def telemetry_params_input(script=SCRIPT):
62
+ return TelemetryParamsInput(page_url="https://example.com/", script=script)
63
+
64
+
65
+ def reese_input(script=SCRIPT):
66
+ return ReeseInput(user_agent="ua", accept_language="en-US", ip="1.2.3.4", pageUrl="https://example.com/",
67
+ script=script, script_url="https://example.com/r.js", pow="pow")
68
+
69
+
70
+ def slider_input(script=SCRIPT):
71
+ return DataDomeSliderInput(user_agent="ua", device_link="https://geo.captcha-delivery.com/captcha/?initialCid=x",
72
+ html="<html>", puzzle="pz", piece="pc", parent_url="https://example.com/",
73
+ accept_language="en-US", ip="1.2.3.4", script=script)
74
+
75
+
76
+ def interstitial_input(script=SCRIPT):
77
+ return DataDomeInterstitialInput(user_agent="ua", device_link="https://geo.captcha-delivery.com/x", html="<html>",
78
+ accept_language="en-US", ip="1.2.3.4", script=script)
79
+
80
+
81
+ # Each call: (name, make input, method name, the request body the SDK sent before script hashes)
82
+ CALLS = (
83
+ ("sensor", sensor_input, "generate_sensor_data", lambda i: {
84
+ "userAgent": "ua", "abck": "abck", "bmsz": "bmsz", "version": "3", "pageUrl": "https://example.com/",
85
+ "script": SCRIPT, "scriptUrl": "https://example.com/s.js", "context": "", "ip": "1.2.3.4",
86
+ "acceptLanguage": "en-US"}),
87
+ ("telemetry", telemetry_input, "generate_telemetry", lambda i: {
88
+ "userAgent": "ua", "abck": "abck", "bmsz": "bmsz", "version": "", "pageUrl": "https://example.com/",
89
+ "script": SCRIPT, "scriptUrl": "https://example.com/s.js", "context": "", "ip": "1.2.3.4",
90
+ "acceptLanguage": "en-US", "j": "AAQ"}),
91
+ ("telemetry params", telemetry_params_input, "get_telemetry_params", lambda i: {
92
+ "pageUrl": "https://example.com/", "script": SCRIPT, "context": ""}),
93
+ ("sbsd", sbsd_input, "generate_sbsd_data", lambda i: {
94
+ "userAgent": "ua", "uuid": "uuid", "pageUrl": "https://example.com/", "o": "o", "script": SCRIPT,
95
+ "acceptLanguage": "en-US", "ip": "1.2.3.4", "context": ""}),
96
+ ("reese84", reese_input, "generate_reese84_sensor", lambda i: {
97
+ "userAgent": "ua", "acceptLanguage": "en-US", "ip": "1.2.3.4", "scriptUrl": "https://example.com/r.js",
98
+ "pageUrl": "https://example.com/", "pow": "pow", "script": SCRIPT}),
99
+ ("slider", slider_input, "generate_slider_payload", lambda i: i.to_dict()),
100
+ ("interstitial", interstitial_input, "generate_interstitial_payload", lambda i: i.to_dict()),
101
+ )
102
+
103
+
104
+ def first_value(res):
105
+ # the payload field is named payload, header (telemetry) or path (telemetry params)
106
+ for field in ("payload", "header", "path"):
107
+ if hasattr(res, field):
108
+ return getattr(res, field)
109
+
110
+
111
+ def hashed(body):
112
+ out = {k: v for k, v in body.items() if k != "script"}
113
+ out["scriptHash"] = SCRIPT_HASH
114
+ return out
115
+
116
+
117
+ class Sync(unittest.TestCase):
118
+ def call(self, api, method, input_data):
119
+ s = Session("test-key", client=httpx.Client(transport=httpx.MockTransport(api)))
120
+ return getattr(s, method)(input_data)
121
+
122
+ def test_unseen_script_sends_the_hash_then_the_script(self):
123
+ for name, make, method, full in CALLS:
124
+ with self.subTest(name):
125
+ api, input_data = FakeAPI(), make()
126
+ before = copy.deepcopy(vars(input_data))
127
+ res = self.call(api, method, input_data)
128
+ self.assertEqual(first_value(res), "p")
129
+ want = full(input_data)
130
+ self.assertEqual(api.sent, [hashed(want), want])
131
+ self.assertEqual(vars(input_data), before)
132
+
133
+ def test_known_hash_sends_only_the_hash(self):
134
+ for name, make, method, full in CALLS:
135
+ with self.subTest(name):
136
+ api, input_data = FakeAPI(known={SCRIPT_HASH}), make()
137
+ before = copy.deepcopy(vars(input_data))
138
+ self.call(api, method, input_data)
139
+ self.assertEqual(api.sent, [hashed(full(input_data))])
140
+ self.assertNotIn("script", api.sent[0])
141
+ self.assertEqual(vars(input_data), before)
142
+
143
+ def test_script_is_sent_once_then_the_hash_is_reused(self):
144
+ api = FakeAPI()
145
+ s = Session("test-key", client=httpx.Client(transport=httpx.MockTransport(api)))
146
+ s.generate_sensor_data(sensor_input())
147
+ s.generate_sensor_data(sensor_input())
148
+ self.assertEqual([("script" in b, "scriptHash" in b) for b in api.sent],
149
+ [(False, True), (True, False), (False, True)])
150
+
151
+ def test_error_after_the_script_is_returned(self):
152
+ api = FakeAPI(after_script=(400, {"error": "invalid script"}))
153
+ with self.assertRaisesRegex(Exception, "invalid script"):
154
+ self.call(api, "generate_sensor_data", sensor_input())
155
+ self.assertEqual(len(api.sent), 2)
156
+
157
+ def test_second_script_required_is_returned_without_another_retry(self):
158
+ api = FakeAPI(after_script=(422, {"error": "script_required"}))
159
+ with self.assertRaisesRegex(Exception, "script_required"):
160
+ self.call(api, "generate_reese84_sensor", reese_input())
161
+ self.assertEqual(len(api.sent), 2)
162
+
163
+ def test_other_answers_to_the_hash_are_returned_as_is(self):
164
+ for status, body, pattern in ((422, {"error": "something else"}, "something else"),
165
+ (400, {"error": "bad request"}, "bad request"),
166
+ (500, {}, "status code: 500")):
167
+ with self.subTest(status=status, body=body):
168
+ api = lambda request, status=status, body=body: httpx.Response(status, json=body)
169
+ sent = []
170
+
171
+ def handler(request, api=api):
172
+ sent.append(json.loads(request.content))
173
+ return api(request)
174
+
175
+ with self.assertRaisesRegex(Exception, pattern):
176
+ self.call(handler, "generate_sbsd_data", sbsd_input())
177
+ self.assertEqual(len(sent), 1)
178
+ self.assertIn("scriptHash", sent[0])
179
+
180
+ def test_empty_script_requests_are_sent_unchanged(self):
181
+ api = FakeAPI()
182
+ self.call(api, "generate_sensor_data", sensor_input(script="", context="ctx"))
183
+ self.call(api, "generate_sbsd_data", sbsd_input(script="", context="ctx"))
184
+ self.call(api, "generate_reese84_sensor", reese_input(script=""))
185
+ self.call(api, "generate_slider_payload", slider_input(script=""))
186
+ self.assertEqual(len(api.sent), 4)
187
+ for body in api.sent:
188
+ self.assertNotIn("scriptHash", body)
189
+ self.assertEqual((api.sent[0]["script"], api.sent[0]["context"]), ("", "ctx"))
190
+ self.assertEqual((api.sent[1]["script"], api.sent[1]["context"]), ("", "ctx"))
191
+ self.assertEqual(api.sent[2]["script"], "")
192
+ self.assertNotIn("script", api.sent[3])
193
+
194
+
195
+ class Async(unittest.TestCase):
196
+ def call(self, api, method, input_data):
197
+ async def go():
198
+ client = httpx.AsyncClient(transport=httpx.MockTransport(api))
199
+ async with SessionAsync("test-key", client=client) as s:
200
+ res = await getattr(s, method)(input_data)
201
+ await client.aclose()
202
+ return res
203
+
204
+ return asyncio.run(go())
205
+
206
+ def test_unseen_script_sends_the_hash_then_the_script(self):
207
+ for name, make, method, full in CALLS:
208
+ with self.subTest(name):
209
+ api, input_data = FakeAPI(), make()
210
+ before = copy.deepcopy(vars(input_data))
211
+ res = self.call(api, method, input_data)
212
+ self.assertEqual(first_value(res), "p")
213
+ want = full(input_data)
214
+ self.assertEqual(api.sent, [hashed(want), want])
215
+ self.assertEqual(vars(input_data), before)
216
+
217
+ def test_known_hash_sends_only_the_hash(self):
218
+ for name, make, method, full in CALLS:
219
+ with self.subTest(name):
220
+ api = FakeAPI(known={SCRIPT_HASH})
221
+ self.call(api, method, make())
222
+ self.assertEqual(api.sent, [hashed(full(make()))])
223
+
224
+ def test_error_after_the_script_is_returned(self):
225
+ api = FakeAPI(after_script=(400, {"error": "invalid script"}))
226
+ with self.assertRaisesRegex(Exception, "invalid script"):
227
+ self.call(api, "generate_slider_payload", slider_input())
228
+ self.assertEqual(len(api.sent), 2)
229
+
230
+ def test_empty_script_requests_are_sent_unchanged(self):
231
+ api = FakeAPI()
232
+ self.call(api, "generate_sensor_data", sensor_input(script="", context="ctx"))
233
+ self.call(api, "generate_sbsd_data", sbsd_input(script="", context="ctx"))
234
+ self.assertEqual(len(api.sent), 2)
235
+ for body in api.sent:
236
+ self.assertNotIn("scriptHash", body)
237
+ self.assertEqual((body["script"], body["context"]), ("", "ctx"))
238
+
239
+
240
+ class Hash(unittest.TestCase):
241
+ def test_lowercase_hex_sha256_of_utf8(self):
242
+ from hyper_sdk.shared import script_hash
243
+ self.assertEqual(script_hash("abc"), "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad")
244
+ self.assertEqual(script_hash(SCRIPT), SCRIPT_HASH)
245
+
246
+
247
+ if __name__ == "__main__":
248
+ unittest.main()
File without changes
File without changes
File without changes