Metadata-Version: 2.4
Name: hyper_sdk
Version: 4.1.0
Summary: Hyper Solutions Python SDK
License: MIT License
        
        Copyright (c) 2024 Hyper Solutions
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: homepage, https://github.com/Hyper-Solutions/hyper-sdk-py
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Framework :: AsyncIO
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx[http2]>=0.24.0
Requires-Dist: certifi>=2024.2.2
Requires-Dist: charset-normalizer>=3.3.2
Requires-Dist: idna>=3.6
Requires-Dist: jsonpickle>=3.0.3
Requires-Dist: PyJWT>=2.8.0
Requires-Dist: urllib3>=2.2.1
Dynamic: license-file

# Hyper Solutions SDK - Python Library for Bot Protection Bypass (Akamai, Incapsula, Kasada, DataDome)

![Python Version](https://img.shields.io/badge/Python-3.8+-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![PyPI Version](https://img.shields.io/pypi/v/hyper-sdk)
![PyPI Downloads](https://img.shields.io/pypi/dm/hyper-sdk)

[![](https://dcbadge.limes.pink/api/server/akamai)](https://discord.gg/akamai)

A powerful **Python SDK** for bypassing modern bot protection systems including **Akamai Bot Manager**, **Incapsula**, **Kasada**, and **DataDome**. Generate valid cookies, solve anti-bot challenges, and automate protected endpoints with ease.

Perfect for **web scraping**, **automation**, and **data collection** from protected websites.

## 🔑 Getting API Access

Before using this SDK, you'll need an API key from Hyper Solutions:

1. **Visit [hypersolutions.co](https://hypersolutions.co/?utm_source=github&utm_medium=sdk_readme&utm_campaign=python_sdk_api_access)** to create your account
2. **Choose your plan**:
    - 💳 **Pay-as-you-go**: Perfect for testing and small-scale usage
    - 📊 **Subscription plans**: Cost-effective for high-volume applications
3. **Get your API key** from the dashboard
4. **Start bypassing bot protection** with this SDK!

## 🚀 Quick Start

```python
from hyper_sdk import Session, SensorInput

session = Session("your-api-key")

# Generate Akamai sensor data
result = session.generate_sensor_data(SensorInput(
    # sensor input fields
))

print(f"Generated sensor data: {result.payload}")
print(f"Sensor context: {result.context}")
```

Every `generate_*` method returns a result object (`SensorResult`, `SbsdResult`, ...), so fields the API adds later arrive without breaking your code.

### Client hints (Accept-CH)

Sensor, SBSD, Reese84, Kasada payload and DataDome results carry `client_hints`: the `sec-ch-*`, `device-memory`, `dpr`, `viewport-width`, `ect`, `rtt` and `downlink` headers for the device the payload was generated for, keyed by lowercase header name and ready to send verbatim. Send only the ones the site asked for in its `Accept-CH` response header:

```python
requested = [h.strip().lower() for h in response.headers.get("accept-ch", "").split(",") if h.strip()]
hints = {name: result.client_hints[name] for name in requested if result.client_hints and name in result.client_hints}
```

`client_hints` is `None` when the API returns none (Safari user agents, and payloads built by a remote browser).

## ✨ Features

- 🛡️ **Akamai Bot Manager**: Generate sensor data, handle pixel challenges, validate cookies
- 🔒 **Incapsula Protection**: Generate Reese84 sensors and UTMVC cookies
- ⚡ **Kasada Bypass**: Generate payload data (CT) and POW tokens (CD)
- 🎯 **DataDome Solutions**: Solve tags, slider captchas and interstitial challenges
- 🔧 **Easy Integration**: Simple Python API with async/await support
- ⚙️ **Flexible Configuration**: Custom HTTP clients and session management

## 📦 Installation

Install the Hyper Solutions SDK for Python using:

```bash
pip install hyper-sdk
```

## 📋 Table of Contents

- [Quick Start](#-quick-start)
- [Installation](#-installation)
- [Basic Usage](#-basic-usage)
- [Akamai Bot Manager](#-akamai-bot-manager)
- [Incapsula Protection](#-incapsula-protection)
- [Kasada Bypass](#-kasada-bypass)
- [DataDome Solutions](#-datadome-solutions)
- [Documentation](#-documentation)
- [Contributing](#-contributing)
- [License](#-license)

## 🔧 Basic Usage

### Creating a Session

Initialize the SDK with your API key to start bypassing bot protection:

```python
from hyper_sdk import Session

# Basic session
session = Session("your-api-key")

# Advanced session with custom configuration
session = Session(
    api_key="your-api-key",
    jwt_key="your-jwt-key",
    app_key="your-app-key",
    app_secret="your-app-secret",
    client=custom_http_client
)
```

## 🛡️ Akamai Bot Manager

Bypass **Akamai Bot Manager** protection with sensor data generation, cookie validation, and challenge solving.

### Generating Sensor Data

Generate sensor data for valid **Akamai cookies** and bot detection bypass:

```python
result = await session.generate_sensor_data(SensorInput(
    # Configure sensor parameters
))
# result.payload is the sensor data, result.context goes into the next SensorInput
```

### SBSD

Generate **SBSD** payloads. The first request of a session sends the script, later ones send the returned context. A hard block (an SBSD POST with a `t` parameter) always sends the script with an empty context, never one from an earlier request:

```python
from hyper_sdk import SbsdInput

result = session.generate_sbsd_data(SbsdInput(
    # other sbsd input fields
    script=script,
    script_url=script_url,  # optional: absolute src of the SBSD script tag, query included
))
# POST result.payload; pass result.context in the next SbsdInput instead of script
```

### Handling Sec-Cpt Challenges

Solve **sec-cpt challenges** with built-in parsing and payload generation:

```python
from hyper_sdk.akamai import SecCptChallenge

# Parse sec-cpt challenge from HTML
challenge = SecCptChallenge.parse(html_content)

# Or parse from JSON response
challenge = SecCptChallenge.parse_from_json(json_response)

# Generate challenge response payload
payload = challenge.generate_sec_cpt_payload(sec_cpt_cookie)

# Handle challenge timing requirements
challenge.sleep()
```

### Cookie Validation

Validate **Akamai _abck cookies** and session states:

```python
from hyper_sdk.akamai import is_cookie_valid, is_cookie_invalidated

# Check if cookie is valid for the current request count
is_valid = is_cookie_valid(cookie_value, request_count)

# Check if cookie has been invalidated and needs refresh
needs_refresh = is_cookie_invalidated(cookie_value)
```

### Pixel Challenge Solving

Handle **Akamai pixel challenges** for advanced bot detection bypass:

```python
from hyper_sdk import PixelInput
from hyper_sdk.akamai import parse_pixel_html_var, parse_pixel_script_url, parse_pixel_script_var

# Parse pixel challenge data
html_var = parse_pixel_html_var(html_content)
script_url, post_url = parse_pixel_script_url(html_content)
script_var = parse_pixel_script_var(script_content)

# Generate pixel data
result = session.generate_pixel_data(PixelInput(
    # pixel input fields
))
# result.payload is the pixel data
```

## 🔒 Incapsula Protection

Bypass **Incapsula bot detection** with Reese84 sensors and UTMVC cookie generation.

### Generating Reese84 Sensors

Create **Reese84 sensor data** for Incapsula bypass:

```python
from hyper_sdk import ReeseInput

result = session.generate_reese84_sensor(ReeseInput(
    # reese input fields
))
# result.payload is the sensor, result.client_hints the Accept-CH headers
```

### UTMVC Cookie Generation

Generate **UTMVC cookies** for Incapsula protection bypass:

```python
from hyper_sdk import UtmvcInput

result = session.generate_utmvc_cookie(UtmvcInput(
    # utmvc input fields
))
# result.payload is the ___utmvc cookie, result.swhanedl the swhanedl value
```

### Script Path Parsing

Parse **UTMVC script paths** and generate submit paths:

```python
from hyper_sdk.incapsula import parse_utmvc_script_path, get_utmvc_submit_path

# Parse script path from content
script_path = parse_utmvc_script_path(script_content)

# Generate unique submit path
submit_path = get_utmvc_submit_path()
```

### Dynamic Reese Script Parsing

Parse dynamic Reese84 script paths from interruption pages:

```python
from hyper_sdk.incapsula import parse_dynamic_reese_script

sensor_path, script_path = parse_dynamic_reese_script(html_content, "https://example.com")
```

## ⚡ Kasada Bypass

Defeat **Kasada Bot Manager** with payload generation and POW solving.

### Generating Payload Data (CT)

Create **x-kpsdk-ct tokens** for Kasada bypass:

```python
from hyper_sdk import KasadaPayloadInput

result = session.generate_kasada_payload(KasadaPayloadInput(
    # kasada payload input fields
    # strict=True refuses a payload built on a signal the API cannot identify
    # yet, instead of returning one built on a guess. Optional, off by default.
))
# POST the base64-decoded result.payload to /tl with the x-kpsdk-* values in result.headers.
# result.client_hints are the Accept-CH headers: send only the ones the site asked for.
```

### Generating POW Data (CD)

Solve **Kasada Proof-of-Work** challenges for x-kpsdk-cd tokens:

```python
from hyper_sdk import KasadaPowInput

result = session.generate_kasada_pow(KasadaPowInput(
    # kasada pow input fields
))
# result.payload is the x-kpsdk-cd value
```

## 🤖 Vercel BotID

Bypass **Vercel BotID** protection by generating the required `x-is-human` header.

### Generating the x-is-human Header

Create the **x-is-human header** for Vercel BotID bypass:

```python
from hyper_sdk import BotIDHeaderInput

result = session.generate_botid_header(BotIDHeaderInput(
    script=script_body,          # The c.js script content
    user_agent="your-user-agent",
    ip="your-proxy-ip",
    accept_language="en-US,en;q=0.9",
))

# Use the header in your requests
headers = {
    "x-is-human": result.payload,
    # ... other headers
}
```

### Script Path Extraction

Extract **Kasada script paths** from blocked pages (HTTP 429):

```python
from hyper_sdk.kasada import parse_kasada_script_path

script_path = parse_kasada_script_path(blocked_page_html)
# Returns: /ips.js?timestamp=...
```

### Mobile User-Agent Generation

Generate the **Kasada mobile `user-agent`** value sent on the native app flow. The mobile SDK derives it as the lowercase hex MD5 of `"<os_version> / <bundle_id> <app_version>"`:

```python
from hyper_sdk import generate_kasada_user_agent

user_agent = generate_kasada_user_agent("18.0.1", "com.example.app", "9.15.0")
# iOS:     os_version = UIDevice.systemVersion, bundle_id = CFBundleIdentifier
# Android: os_version = Build.VERSION.SDK_INT,  bundle_id = package name
# Returns: 7016adc4ba8d433533954ebad33be424
```

Available in `hyper_sdk` 3.1.0 and later.

## 🎯 DataDome Solutions

Solve **DataDome captchas** including slider challenges and interstitial pages.

### Interstitial Challenge Solving

Bypass **DataDome interstitial pages**:

```python
from hyper_sdk import DataDomeInterstitialInput

result = session.generate_interstitial_payload(DataDomeInterstitialInput(
    # interstitial input fields
))

# POST result.payload to https://geo.captcha-delivery.com/interstitial/
# result.client_hints are the Accept-CH headers for the device
```

### Slider Captcha Solving

Solve **DataDome slider captchas** automatically:

```python
from hyper_sdk import DataDomeSliderInput

result = session.generate_slider_payload(DataDomeSliderInput(
    # slider input fields
))

# GET request to result.payload (the check URL)
# result.client_hints are the Accept-CH headers for the device
```

### Tags Payload Generation

Generate **DataDome tags payload**:

```python
from hyper_sdk import DataDomeTagsInput

result = session.generate_tags_payload(DataDomeTagsInput(
    # tags input fields
))
# result.payload is the tags payload
```

### DeviceLink URL Parsing

Extract **DataDome device check URLs** from blocked pages:

```python
from hyper_sdk.datadome import parse_interstitial_device_check_link, parse_slider_device_check_link

# Parse interstitial device links
device_link = parse_interstitial_device_check_link(
    html_content, 
    datadome_cookie, 
    referer_url
)

# Parse slider device links  
device_link = parse_slider_device_check_link(
    html_content, 
    datadome_cookie, 
    referer_url
)
```

### Challenge Script

DataDome sometimes serves a challenge page with the **challenge script in its own file** instead of inlining it in the page:

```html
<script defer src="https://ct.captcha-delivery.com/interstitial.1.33.0.202609141.js"></script>
```

It switches between the two forms per request, so check every challenge page. When the page uses a separate file, fetch it with your own client so the request keeps your proxy, TLS fingerprint and headers, then pass the body as `script`:

```python
from hyper_sdk import DataDomeInterstitialInput
from hyper_sdk.datadome import parse_challenge_script_url

script = ""
script_url = parse_challenge_script_url(html_content)
if script_url is not None:
    script = your_client.get(script_url).text

result = session.generate_interstitial_payload(DataDomeInterstitialInput(
    # other interstitial input fields
    html=html_content,
    script=script,  # empty when the page inlines the script
))
```

The same applies to `DataDomeSliderInput`. One helper covers both challenge types, since the captcha page uses the same tag. `script` is optional and leaving it empty keeps working.

## 📖 Documentation

For detailed documentation on how to use the SDK, including examples and API reference, please visit our documentation website:

[https://docs.justhyped.dev/](https://docs.justhyped.dev/)

### Getting Help

- Check our [documentation](https://docs.justhyped.dev)
- Join our [Discord community](https://discord.gg/akamai)

## 🤝 Contributing

If you find any issues or have suggestions for improvement, please open an issue or submit a pull request.

## 📄 License

This SDK is licensed under the [MIT License](LICENSE).

---

**Keywords**: Python SDK, bot protection bypass, web scraping, Akamai bypass, Incapsula bypass, Kasada bypass, DataDome bypass, anti-bot, captcha solver, automation, reverse engineering, bot detection, web automation
