hyper-sdk 4.1.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.
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/PKG-INFO +32 -1
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/README.md +31 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/__init__.py +1 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/datadome/parse.py +5 -3
- hyper_sdk-4.3.1/hyper_sdk/kasada/dv.py +38 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/kasada_input.py +9 -1
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/results.py +42 -1
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/session.py +28 -1
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/session_async.py +29 -1
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk.egg-info/PKG-INFO +32 -1
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk.egg-info/SOURCES.txt +3 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/pyproject.toml +1 -1
- hyper_sdk-4.3.1/tests/test_challenge_script_url.py +35 -0
- hyper_sdk-4.3.1/tests/test_dv.py +25 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/tests/test_results.py +60 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/LICENSE +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/akamai/__init__.py +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/akamai/pixel.py +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/akamai/script_path.py +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/akamai/sec_cpt.py +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/akamai/stop_signal.py +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/akamai_input.py +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/datadome/__init__.py +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/datadome_input.py +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/incapsula/__init__.py +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/incapsula/dynamic.py +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/incapsula/utmvc.py +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/incapsula_input.py +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/kasada/__init__.py +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/kasada/parse.py +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/kasada/user_agent.py +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/payloads.py +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/shared.py +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk/trustdecision_input.py +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk.egg-info/dependency_links.txt +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk.egg-info/requires.txt +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/hyper_sdk.egg-info/top_level.txt +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/setup.cfg +0 -0
- {hyper_sdk-4.1.0 → hyper_sdk-4.3.1}/tests/test_script_hash.py +0 -0
- {hyper_sdk-4.1.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.1
|
|
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.
|
|
@@ -368,6 +380,25 @@ user_agent = generate_kasada_user_agent("18.0.1", "com.example.app", "9.15.0")
|
|
|
368
380
|
|
|
369
381
|
Available in `hyper_sdk` 3.1.0 and later.
|
|
370
382
|
|
|
383
|
+
### Mobile x-kpsdk-dv Generation
|
|
384
|
+
|
|
385
|
+
On iOS the Kasada SDK (`x-kpsdk-v` i-2.x) also sends an **`x-kpsdk-dv`** header describing the device and the app. Build it from the same values as the user-agent, plus the model identifier, and pass the same value as `dv` on the payload request so the payload is generated on an iPhone with that model's screen and iOS version:
|
|
386
|
+
|
|
387
|
+
```python
|
|
388
|
+
from hyper_sdk import KasadaPayloadInput, generate_kasada_dv, generate_kasada_user_agent
|
|
389
|
+
|
|
390
|
+
user_agent = generate_kasada_user_agent("18.0.1", "com.example.app", "9.15.0")
|
|
391
|
+
dv = generate_kasada_dv("18.0.1", "iPhone13,2", "com.example.app", "9.15.0")
|
|
392
|
+
# hardware_id is the model identifier from utsname.machine ("iPhone13,2" is an iPhone 12)
|
|
393
|
+
|
|
394
|
+
result = session.generate_kasada_payload(KasadaPayloadInput(
|
|
395
|
+
user_agent, ips_link, script, "en-US,en;q=0.9", ip,
|
|
396
|
+
dv=dv, # the x-kpsdk-dv value you send to the site
|
|
397
|
+
))
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
Available in `hyper_sdk` 4.2.0 and later.
|
|
401
|
+
|
|
371
402
|
## 🎯 DataDome Solutions
|
|
372
403
|
|
|
373
404
|
Solve **DataDome captchas** including slider challenges and interstitial pages.
|
|
@@ -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.
|
|
@@ -325,6 +337,25 @@ user_agent = generate_kasada_user_agent("18.0.1", "com.example.app", "9.15.0")
|
|
|
325
337
|
|
|
326
338
|
Available in `hyper_sdk` 3.1.0 and later.
|
|
327
339
|
|
|
340
|
+
### Mobile x-kpsdk-dv Generation
|
|
341
|
+
|
|
342
|
+
On iOS the Kasada SDK (`x-kpsdk-v` i-2.x) also sends an **`x-kpsdk-dv`** header describing the device and the app. Build it from the same values as the user-agent, plus the model identifier, and pass the same value as `dv` on the payload request so the payload is generated on an iPhone with that model's screen and iOS version:
|
|
343
|
+
|
|
344
|
+
```python
|
|
345
|
+
from hyper_sdk import KasadaPayloadInput, generate_kasada_dv, generate_kasada_user_agent
|
|
346
|
+
|
|
347
|
+
user_agent = generate_kasada_user_agent("18.0.1", "com.example.app", "9.15.0")
|
|
348
|
+
dv = generate_kasada_dv("18.0.1", "iPhone13,2", "com.example.app", "9.15.0")
|
|
349
|
+
# hardware_id is the model identifier from utsname.machine ("iPhone13,2" is an iPhone 12)
|
|
350
|
+
|
|
351
|
+
result = session.generate_kasada_payload(KasadaPayloadInput(
|
|
352
|
+
user_agent, ips_link, script, "en-US,en;q=0.9", ip,
|
|
353
|
+
dv=dv, # the x-kpsdk-dv value you send to the site
|
|
354
|
+
))
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
Available in `hyper_sdk` 4.2.0 and later.
|
|
358
|
+
|
|
328
359
|
## 🎯 DataDome Solutions
|
|
329
360
|
|
|
330
361
|
Solve **DataDome captchas** including slider challenges and interstitial pages.
|
|
@@ -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,
|
|
9
|
-
#
|
|
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
|
|
13
|
+
r"""<script[^>]+src\s*=\s*["']([^"']*/[a-z_-]+\.\d+\.\d+\.\d+(?:\.[^"']*)?\.js)["']"""
|
|
12
14
|
)
|
|
13
15
|
|
|
14
16
|
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
import base64
|
|
2
|
+
import json
|
|
3
|
+
|
|
4
|
+
__all__ = ["generate_kasada_dv"]
|
|
5
|
+
|
|
6
|
+
# The key the Kasada iOS SDK XORs the x-kpsdk-dv header with.
|
|
7
|
+
_DV_KEY = b"9d9a1f73-a488-464c-9f73-8c87d018363c"
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def generate_kasada_dv(os_version: str, hardware_id: str, app_id: str, app_version: str) -> str:
|
|
11
|
+
"""
|
|
12
|
+
Generates the x-kpsdk-dv header value the Kasada iOS SDK (i-2.x) sends.
|
|
13
|
+
|
|
14
|
+
The value is base64 of {"osVersion","hardwareId","appId","appVersion"} XORed with a key
|
|
15
|
+
fixed in the SDK. app_id and app_version are the same values generate_kasada_user_agent
|
|
16
|
+
takes as bundle_id and app_version, so a user-agent and a dv built from one set of inputs
|
|
17
|
+
describe the same app and device.
|
|
18
|
+
|
|
19
|
+
Send the same value as the dv field of KasadaPayloadInput, so the payload is generated on
|
|
20
|
+
a device with that model's screen and iOS release.
|
|
21
|
+
|
|
22
|
+
Args:
|
|
23
|
+
os_version (str): UIDevice.systemVersion (e.g. "18.0.1").
|
|
24
|
+
hardware_id (str): The model identifier from utsname.machine (e.g. "iPhone13,2" for
|
|
25
|
+
an iPhone 12), not the marketing name.
|
|
26
|
+
app_id (str): The app bundle id (e.g. "com.example.app").
|
|
27
|
+
app_version (str): The app version (e.g. "9.15.0").
|
|
28
|
+
|
|
29
|
+
Returns:
|
|
30
|
+
str: The x-kpsdk-dv header value.
|
|
31
|
+
"""
|
|
32
|
+
plain = json.dumps(
|
|
33
|
+
{"osVersion": os_version, "hardwareId": hardware_id, "appId": app_id, "appVersion": app_version},
|
|
34
|
+
separators=(",", ":"),
|
|
35
|
+
ensure_ascii=False,
|
|
36
|
+
).encode("utf-8")
|
|
37
|
+
key = _DV_KEY[:len(plain)]
|
|
38
|
+
return base64.b64encode(bytes(b ^ key[i % len(key)] for i, b in enumerate(plain))).decode("ascii")
|
|
@@ -21,7 +21,7 @@ class KasadaPowInput:
|
|
|
21
21
|
|
|
22
22
|
class KasadaPayloadInput:
|
|
23
23
|
def __init__(self, user_agent: str, ips_link: str, script: str, accept_language: str, ip: str,
|
|
24
|
-
strict: bool = False):
|
|
24
|
+
strict: bool = False, dv: str = ""):
|
|
25
25
|
# UserAgent must be a Chrome Windows User-Agent.
|
|
26
26
|
self.user_agent = user_agent
|
|
27
27
|
|
|
@@ -41,6 +41,12 @@ class KasadaPayloadInput:
|
|
|
41
41
|
# set". Off by default: such a payload usually still works.
|
|
42
42
|
self.strict = strict
|
|
43
43
|
|
|
44
|
+
# Dv is the x-kpsdk-dv header the iOS app flow sends, exactly as sent (see
|
|
45
|
+
# generate_kasada_dv). Optional, iOS app user agents only: the payload is then
|
|
46
|
+
# generated on a device with the screen of the model it names and the iOS
|
|
47
|
+
# release it names, so the two agree.
|
|
48
|
+
self.dv = dv
|
|
49
|
+
|
|
44
50
|
def to_dict(self):
|
|
45
51
|
result = {
|
|
46
52
|
"userAgent": self.user_agent,
|
|
@@ -51,6 +57,8 @@ class KasadaPayloadInput:
|
|
|
51
57
|
}
|
|
52
58
|
if self.strict:
|
|
53
59
|
result["strict"] = True
|
|
60
|
+
if self.dv:
|
|
61
|
+
result["dv"] = self.dv
|
|
54
62
|
return result
|
|
55
63
|
|
|
56
64
|
class KasadaVersionInput:
|
|
@@ -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.1
|
|
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.
|
|
@@ -368,6 +380,25 @@ user_agent = generate_kasada_user_agent("18.0.1", "com.example.app", "9.15.0")
|
|
|
368
380
|
|
|
369
381
|
Available in `hyper_sdk` 3.1.0 and later.
|
|
370
382
|
|
|
383
|
+
### Mobile x-kpsdk-dv Generation
|
|
384
|
+
|
|
385
|
+
On iOS the Kasada SDK (`x-kpsdk-v` i-2.x) also sends an **`x-kpsdk-dv`** header describing the device and the app. Build it from the same values as the user-agent, plus the model identifier, and pass the same value as `dv` on the payload request so the payload is generated on an iPhone with that model's screen and iOS version:
|
|
386
|
+
|
|
387
|
+
```python
|
|
388
|
+
from hyper_sdk import KasadaPayloadInput, generate_kasada_dv, generate_kasada_user_agent
|
|
389
|
+
|
|
390
|
+
user_agent = generate_kasada_user_agent("18.0.1", "com.example.app", "9.15.0")
|
|
391
|
+
dv = generate_kasada_dv("18.0.1", "iPhone13,2", "com.example.app", "9.15.0")
|
|
392
|
+
# hardware_id is the model identifier from utsname.machine ("iPhone13,2" is an iPhone 12)
|
|
393
|
+
|
|
394
|
+
result = session.generate_kasada_payload(KasadaPayloadInput(
|
|
395
|
+
user_agent, ips_link, script, "en-US,en;q=0.9", ip,
|
|
396
|
+
dv=dv, # the x-kpsdk-dv value you send to the site
|
|
397
|
+
))
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
Available in `hyper_sdk` 4.2.0 and later.
|
|
401
|
+
|
|
371
402
|
## 🎯 DataDome Solutions
|
|
372
403
|
|
|
373
404
|
Solve **DataDome captchas** including slider challenges and interstitial pages.
|
|
@@ -28,8 +28,11 @@ hyper_sdk/incapsula/__init__.py
|
|
|
28
28
|
hyper_sdk/incapsula/dynamic.py
|
|
29
29
|
hyper_sdk/incapsula/utmvc.py
|
|
30
30
|
hyper_sdk/kasada/__init__.py
|
|
31
|
+
hyper_sdk/kasada/dv.py
|
|
31
32
|
hyper_sdk/kasada/parse.py
|
|
32
33
|
hyper_sdk/kasada/user_agent.py
|
|
34
|
+
tests/test_challenge_script_url.py
|
|
35
|
+
tests/test_dv.py
|
|
33
36
|
tests/test_results.py
|
|
34
37
|
tests/test_script_hash.py
|
|
35
38
|
tests/test_user_agent.py
|
|
@@ -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()
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import unittest
|
|
2
|
+
|
|
3
|
+
from hyper_sdk import KasadaPayloadInput, generate_kasada_dv, generate_kasada_user_agent
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class KasadaDv(unittest.TestCase):
|
|
7
|
+
# A user-agent and dv built from one set of inputs, in the four-field form the i-2.x iOS SDK sends.
|
|
8
|
+
def test_matches_documented_vector(self):
|
|
9
|
+
self.assertEqual(
|
|
10
|
+
generate_kasada_dv("18.0.1", "iPhone13,2", "com.example.app", "9.15.0"),
|
|
11
|
+
"QkZWEmcDRUBEDloaAg8FDhpTAwhEGxFFWRFcQAVCVHFXFAlBUDRRDl8DBgABUxYUGkxERn0HDwNEVFxAFgZAVglAXV0dV0MTG0gbAEEWYVZfEl1XVg8OFA1NHAxIBxFQ",
|
|
12
|
+
)
|
|
13
|
+
self.assertEqual(
|
|
14
|
+
generate_kasada_user_agent("18.0.1", "com.example.app", "9.15.0"),
|
|
15
|
+
"7016adc4ba8d433533954ebad33be424",
|
|
16
|
+
)
|
|
17
|
+
|
|
18
|
+
def test_payload_input_sends_dv_only_when_set(self):
|
|
19
|
+
base = ("ua", "https://example.com/ips.js", "script", "en-US", "203.0.113.7")
|
|
20
|
+
self.assertNotIn("dv", KasadaPayloadInput(*base).to_dict())
|
|
21
|
+
self.assertEqual(KasadaPayloadInput(*base, dv="abc").to_dict()["dv"], "abc")
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
if __name__ == "__main__":
|
|
25
|
+
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
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|