hyper-sdk 0.1.0__tar.gz

hyper_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

hyper_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.1
+Name: hyper_sdk
+Version: 0.1.0
+Summary: Hyper Solutions Python SDK
+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
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+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: requests==2.31.0
+Requires-Dist: urllib3==2.2.1
+
+# Hyper Solutions SDK for Python
+
+## Installation
+
+To use the Hyper Solutions SDK in your Python project, you need to install it using the following command:
+
+```
+pip install hyper-sdk
+```
+
+## Usage
+
+### Creating a Session
+
+To start using the SDK, you need to create a new `Session` instance by providing your API key:
+
+```python
+from hyper_sdk import Session
+
+session = Session(api_key="your-api-key")
+```
+
+You can also optionally set a JWT key and a custom HTTP client:
+
+```python
+from hyper_sdk import Session
+
+session = Session(api_key="your-api-key", jwt_key="your-jwt-key", client=custom_http_client)
+```
+
+## Akamai
+
+The Akamai package provides functions for interacting with Akamai Bot Manager, including generating sensor data, parsing script path, parsing pixel challenges, and handling sec-cpt challenges.
+
+### Generating Sensor Data
+
+To generate sensor data required for generating valid Akamai cookies, use the `generate_sensor_data` method:
+
+```python
+from hyper_sdk import SensorInput
+
+sensor_input = SensorInput(
+    page_url="https://example.com/",
+    user_agent="your-user-agent",
+    abck="your-abck-cookie",
+    bmsz="your-bmsz-cookie",
+    version="2.0"
+)
+sensor_data = session.generate_sensor_data(sensor_input)
+```
+
+### Parsing Script Path
+
+To parse the Akamai Bot Manager script path from the given HTML code, use the `parse_script_path` function from the `script_path` module:
+
+```python
+from hyper_sdk.akamai.script_path import parse_script_path
+
+script_path = parse_script_path(html_source)
+```
+
+### Handling Sec-Cpt Challenges
+
+The Akamai package provides functions for handling sec-cpt challenges:
+
+- `SecCptChallenge.parse`: Parses a sec-cpt challenge from an HTML source.
+- `generate_sec_cpt_payload`: Generates a sec-cpt payload using the provided sec-cpt cookie.
+- `update_sec_cpt_challenge_data`: Updates the challenge data of a `SecCptChallenge` instance from a response body.
+
+Example usage:
+
+```python
+from hyper_sdk.akamai.sec_cpt import SecCptChallenge
+
+challenge = SecCptChallenge.parse(html_source)
+payload = challenge.generate_sec_cpt_payload(sec_cpt_cookie)
+challenge.update_sec_cpt_challenge_data(response_body)
+```
+
+### Validating Cookies
+
+The Akamai package provides functions for validating cookies:
+
+- `is_cookie_valid`: Determines if the provided `_abck` cookie value is valid based on the given request count.
+- `is_cookie_invalidated`: Determines if the current session requires more sensors to be sent.
+
+Example usage:
+
+```python
+from hyper_sdk.akamai.stop_signal import is_cookie_valid, is_cookie_invalidated
+
+is_valid = is_cookie_valid(abck_cookie, request_count)
+is_invalidated = is_cookie_invalidated(abck_cookie)
+```
+
+### Generating Pixel Data
+
+To generate pixel data, use the `generate_pixel_data` method:
+
+```python
+from hyper_sdk import PixelInput
+
+pixel_input = PixelInput(
+    user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/93.0.4577.82 Safari/537.36",
+    html_var="your-html-var",
+    script_var="your-script-var"
+)
+pixel_data = session.generate_pixel_data(pixel_input)
+```
+
+### Parsing Pixel Challenges
+
+The Akamai package provides functions for parsing pixel challenges:
+
+- `parse_pixel_html_var`: Parses the required pixel challenge variable from the given HTML code.
+- `parse_pixel_script_url`: Parses the script URL of the pixel challenge script and the URL to post a generated payload to from the given HTML code.
+- `parse_pixel_script_var`: Parses the dynamic value from the pixel script.
+
+Example usage:
+
+```python
+from hyper_sdk.akamai.pixel import parse_pixel_html_var, parse_pixel_script_url, parse_pixel_script_var
+
+html_var = parse_pixel_html_var(html_source)
+script_url, post_url = parse_pixel_script_url(html_source)
+script_var = parse_pixel_script_var(script_source)
+```
+
+
+## Incapsula
+
+The Incapsula package provides functions for interacting with Imperva Incapsula, including generating Reese84 sensor data, UTMVC cookies, and parsing UTMVC script paths.
+
+### Generating Reese84 Sensor
+
+To generate sensor data required for generating valid Reese84 cookies, use the `generate_reese84_sensor` method:
+
+```python
+sensor_data = session.generate_reese84_sensor(site="example.com", user_agent="your-user-agent")
+```
+
+### Generating UTMVC Cookie
+
+To generate the UTMVC cookie using the Hyper Solutions API, use the `generate_utmvc_cookie` method:
+
+```python
+from hyper_sdk import UtmvcInput
+
+utmvc_input = UtmvcInput(
+    user_agent="your-user-agent",
+    session_ids=["session-id-1", "session-id-2"],
+    script="your-script"
+)
+utmvc_cookie = session.generate_utmvc_cookie(utmvc_input)
+```
+
+### Parsing UTMVC Script Path
+
+To parse the UTMVC script path from a given script content, use the `parse_utmvc_script_path` function from the `utmvc` module:
+
+```python
+from hyper_sdk.incapsula.utmvc import parse_utmvc_script_path
+
+script_path = parse_utmvc_script_path(script_content)
+```
+
+### Generating UTMVC Submit Path
+
+To generate a unique UTMVC submit path with a random query parameter, use the `get_utmvc_submit_path` function from the `utmvc` module:
+
+```python
+from hyper_sdk.incapsula.utmvc import get_utmvc_submit_path
+
+submit_path = get_utmvc_submit_path()
+```

hyper_sdk-0.1.0/README.md

@@ -0,0 +1,175 @@
+# Hyper Solutions SDK for Python
+
+## Installation
+
+To use the Hyper Solutions SDK in your Python project, you need to install it using the following command:
+
+```
+pip install hyper-sdk
+```
+
+## Usage
+
+### Creating a Session
+
+To start using the SDK, you need to create a new `Session` instance by providing your API key:
+
+```python
+from hyper_sdk import Session
+
+session = Session(api_key="your-api-key")
+```
+
+You can also optionally set a JWT key and a custom HTTP client:
+
+```python
+from hyper_sdk import Session
+
+session = Session(api_key="your-api-key", jwt_key="your-jwt-key", client=custom_http_client)
+```
+
+## Akamai
+
+The Akamai package provides functions for interacting with Akamai Bot Manager, including generating sensor data, parsing script path, parsing pixel challenges, and handling sec-cpt challenges.
+
+### Generating Sensor Data
+
+To generate sensor data required for generating valid Akamai cookies, use the `generate_sensor_data` method:
+
+```python
+from hyper_sdk import SensorInput
+
+sensor_input = SensorInput(
+    page_url="https://example.com/",
+    user_agent="your-user-agent",
+    abck="your-abck-cookie",
+    bmsz="your-bmsz-cookie",
+    version="2.0"
+)
+sensor_data = session.generate_sensor_data(sensor_input)
+```
+
+### Parsing Script Path
+
+To parse the Akamai Bot Manager script path from the given HTML code, use the `parse_script_path` function from the `script_path` module:
+
+```python
+from hyper_sdk.akamai.script_path import parse_script_path
+
+script_path = parse_script_path(html_source)
+```
+
+### Handling Sec-Cpt Challenges
+
+The Akamai package provides functions for handling sec-cpt challenges:
+
+- `SecCptChallenge.parse`: Parses a sec-cpt challenge from an HTML source.
+- `generate_sec_cpt_payload`: Generates a sec-cpt payload using the provided sec-cpt cookie.
+- `update_sec_cpt_challenge_data`: Updates the challenge data of a `SecCptChallenge` instance from a response body.
+
+Example usage:
+
+```python
+from hyper_sdk.akamai.sec_cpt import SecCptChallenge
+
+challenge = SecCptChallenge.parse(html_source)
+payload = challenge.generate_sec_cpt_payload(sec_cpt_cookie)
+challenge.update_sec_cpt_challenge_data(response_body)
+```
+
+### Validating Cookies
+
+The Akamai package provides functions for validating cookies:
+
+- `is_cookie_valid`: Determines if the provided `_abck` cookie value is valid based on the given request count.
+- `is_cookie_invalidated`: Determines if the current session requires more sensors to be sent.
+
+Example usage:
+
+```python
+from hyper_sdk.akamai.stop_signal import is_cookie_valid, is_cookie_invalidated
+
+is_valid = is_cookie_valid(abck_cookie, request_count)
+is_invalidated = is_cookie_invalidated(abck_cookie)
+```
+
+### Generating Pixel Data
+
+To generate pixel data, use the `generate_pixel_data` method:
+
+```python
+from hyper_sdk import PixelInput
+
+pixel_input = PixelInput(
+    user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/93.0.4577.82 Safari/537.36",
+    html_var="your-html-var",
+    script_var="your-script-var"
+)
+pixel_data = session.generate_pixel_data(pixel_input)
+```
+
+### Parsing Pixel Challenges
+
+The Akamai package provides functions for parsing pixel challenges:
+
+- `parse_pixel_html_var`: Parses the required pixel challenge variable from the given HTML code.
+- `parse_pixel_script_url`: Parses the script URL of the pixel challenge script and the URL to post a generated payload to from the given HTML code.
+- `parse_pixel_script_var`: Parses the dynamic value from the pixel script.
+
+Example usage:
+
+```python
+from hyper_sdk.akamai.pixel import parse_pixel_html_var, parse_pixel_script_url, parse_pixel_script_var
+
+html_var = parse_pixel_html_var(html_source)
+script_url, post_url = parse_pixel_script_url(html_source)
+script_var = parse_pixel_script_var(script_source)
+```
+
+
+## Incapsula
+
+The Incapsula package provides functions for interacting with Imperva Incapsula, including generating Reese84 sensor data, UTMVC cookies, and parsing UTMVC script paths.
+
+### Generating Reese84 Sensor
+
+To generate sensor data required for generating valid Reese84 cookies, use the `generate_reese84_sensor` method:
+
+```python
+sensor_data = session.generate_reese84_sensor(site="example.com", user_agent="your-user-agent")
+```
+
+### Generating UTMVC Cookie
+
+To generate the UTMVC cookie using the Hyper Solutions API, use the `generate_utmvc_cookie` method:
+
+```python
+from hyper_sdk import UtmvcInput
+
+utmvc_input = UtmvcInput(
+    user_agent="your-user-agent",
+    session_ids=["session-id-1", "session-id-2"],
+    script="your-script"
+)
+utmvc_cookie = session.generate_utmvc_cookie(utmvc_input)
+```
+
+### Parsing UTMVC Script Path
+
+To parse the UTMVC script path from a given script content, use the `parse_utmvc_script_path` function from the `utmvc` module:
+
+```python
+from hyper_sdk.incapsula.utmvc import parse_utmvc_script_path
+
+script_path = parse_utmvc_script_path(script_content)
+```
+
+### Generating UTMVC Submit Path
+
+To generate a unique UTMVC submit path with a random query parameter, use the `get_utmvc_submit_path` function from the `utmvc` module:
+
+```python
+from hyper_sdk.incapsula.utmvc import get_utmvc_submit_path
+
+submit_path = get_utmvc_submit_path()
+```

hyper_sdk-0.1.0/hyper_sdk/__init__.py

@@ -0,0 +1,6 @@
+from .akamai.pixel import *
+from .akamai.script_path import *
+from .akamai.sec_cpt import *
+from .akamai.stop_signal import *
+from .incapsula.utmvc import *
+from .session import *

hyper_sdk-0.1.0/hyper_sdk/akamai/__init__.py

@@ -0,0 +1,4 @@
+from .pixel import *
+from .script_path import *
+from .sec_cpt import *
+from .stop_signal import *

hyper_sdk-0.1.0/hyper_sdk/akamai/pixel.py

@@ -0,0 +1,83 @@
+import re
+
+pixel_html_expr = re.compile(r'bazadebezolkohpepadr="(\d+)"')
+pixel_script_url_expr = re.compile(r'src="(https?://.+/akam/\d+/\w+)"')
+pixel_script_var_expr = re.compile(r'g=_\[(\d+)]')
+pixel_script_string_array_expr = re.compile(r'var _=\[(.+?)];')
+pixel_script_strings_expr = re.compile(r'("[^",]*")')
+
+
+def parse_pixel_html_var(src: str) -> int:
+    """
+        ParsePixelHtmlVar gets the required pixel challenge variable from the given HTML code src.
+
+        Args:
+            src (str): HTML source code as a string.
+
+        Returns:
+            int: The parsed pixel HTML variable.
+
+        Raises:
+            Exception: If the pixel HTML var is not found in the source.
+    """
+    match = pixel_html_expr.search(src)
+    if match:
+        return int(match.group(1))
+    else:
+        raise Exception("hyper-sdk: pixel HTML var not found")
+
+
+def parse_pixel_script_url(src: str) -> tuple[str, str]:
+    """
+        ParsePixelScriptURL gets the script URL of the pixel challenge script and the URL
+        to post a generated payload to from the given HTML code src.
+
+        Args:
+            src (str): HTML source code as a string.
+
+        Returns:
+            tuple[str, str]: A tuple containing the script URL and the post URL.
+
+        Raises:
+            Exception: If the script URL is not found in the source.
+    """
+    match = pixel_script_url_expr.search(src)
+    if match:
+        script_url = match.group(1)
+        # Create post_url
+        parts = script_url.split("/")
+        parts[-1] = "pixel_" + parts[-1]
+        post_url = "/".join(parts)
+        return script_url, post_url
+    else:
+        raise Exception("hyper-sdk: script URL not found")
+
+
+def parse_pixel_script_var(src: str) -> str:
+    """
+        Gets the dynamic value from the pixel script.
+
+        Args:
+            src (str): HTML source code as a string.
+
+        Returns:
+            str: The dynamic value extracted from the pixel script.
+
+        Raises:
+            Exception: If the script variable is not found or if there are issues extracting it.
+    """
+    index_match = pixel_script_var_expr.search(src)
+    if not index_match:
+        raise Exception("hyper-sdk: script var not found")
+    string_index = int(index_match.group(1))
+
+    array_declaration_match = pixel_script_string_array_expr.search(src)
+    if not array_declaration_match:
+        raise Exception("hyper-sdk: script var not found")
+
+    raw_strings = pixel_script_strings_expr.findall(array_declaration_match.group(1))
+    if string_index >= len(raw_strings):
+        raise Exception("hyper-sdk: script var not found")
+
+    string_value = raw_strings[string_index].strip('"')
+    return string_value

hyper_sdk-0.1.0/hyper_sdk/akamai/script_path.py

@@ -0,0 +1,28 @@
+import re
+
+# Precompiled regular expressions
+script_path_expr = re.compile(r'<script type="text/javascript"\s+(?:nonce=".*?")?\s+src="([a-z\d/\-_]+)"></script>',
+                              re.IGNORECASE)
+
+
+def parse_script_path(src: str) -> str:
+    """
+        Gets the Akamai Bot Manager web SDK path from the given HTML code src.
+
+        This function searches the provided HTML source code for the path of a JavaScript script tag that matches the
+        specified regular expression pattern.
+
+        Args:
+            src (str): The HTML source code as a string.
+
+        Returns:
+            str: The path of the script extracted from the script tag.
+
+        Raises:
+            Exception: If the script path is not found in the source.
+    """
+    match = script_path_expr.search(src)
+    if match:
+        return match.group(1)
+    else:
+        raise "hyper-sdk: script path not found"

hyper_sdk-0.1.0/hyper_sdk/akamai/sec_cpt.py

@@ -0,0 +1,115 @@
+import base64
+import hashlib
+import json
+import os
+import re
+from collections import OrderedDict
+from typing import List
+
+sec_duration_expr = re.compile(r'data-duration=(\d+)')
+sec_challenge_expr = re.compile(r'challenge="(.*?)"')
+sec_page_expr = re.compile(r'src="(/_sec/cp_challenge/ak-challenge-\d+-\d+.htm)"')
+
+
+class SecCptChallengeData:
+    def __init__(self, token: str, timestamp: int, nonce: str, difficulty: int):
+        self.token = token
+        self.timestamp = timestamp
+        self.nonce = nonce
+        self.difficulty = difficulty
+
+
+class SecCptChallenge:
+    def __init__(self, duration: int, challenge_path: str, challenge_data: SecCptChallengeData):
+        self.duration = duration
+        self.challenge_path = challenge_path
+        self.challenge_data = challenge_data
+
+    @staticmethod
+    def parse(html: str) -> 'SecCptChallenge':
+        challenge_data = SecCptChallenge._parse_challenge_data(html)
+        duration = SecCptChallenge._parse_duration(html)
+        challenge_path = SecCptChallenge._parse_challenge_path(html)
+
+        return SecCptChallenge(duration, challenge_path, challenge_data)
+
+    @staticmethod
+    def _parse_challenge_data(src: str) -> SecCptChallengeData:
+        challenge_match = sec_challenge_expr.search(src)
+        if not challenge_match:
+            raise Exception("hyper-sdk: Challenge data not found.")
+
+        decoded_challenge = base64.b64decode(challenge_match.group(1))
+        challenge_data = json.loads(decoded_challenge)
+
+        return SecCptChallengeData(
+            challenge_data.get('token', ''),
+            challenge_data.get('timestamp', 0),
+            challenge_data.get('nonce', ''),
+            challenge_data.get('difficulty', 0)
+        )
+
+    @staticmethod
+    def _parse_duration(src: str) -> int:
+        duration_match = sec_duration_expr.search(src)
+        if not duration_match:
+            raise Exception("hyper-sdk: Duration not found.")
+
+        try:
+            duration = int(duration_match.group(1))
+        except ValueError as e:
+            raise Exception(f"hyper-sdk: Invalid duration value: {e}")
+
+        return duration
+
+    @staticmethod
+    def _parse_challenge_path(src: str) -> str:
+        page_match = sec_page_expr.search(src)
+        if not page_match:
+            raise Exception("hyper-sdk: Challenge path not found.")
+
+        return page_match.group(1)
+
+    def generate_sec_cpt_payload(self, sec_cpt_cookie: str) -> str:
+        sec, _, _ = sec_cpt_cookie.partition("~")
+
+        answers = self._generate_sec_cpt_answers(sec)
+
+        payload = OrderedDict([
+            ("token", self.challenge_data.token),
+            ("answers", answers)
+        ])
+
+        return json.dumps(payload)
+
+    def update_sec_cpt_challenge_data(self, response_body: str):
+        challenge_data = json.loads(response_body)
+        self.challenge_data = SecCptChallengeData(
+            challenge_data.get('token', ''),
+            challenge_data.get('timestamp', 0),
+            challenge_data.get('nonce', ''),
+            challenge_data.get('difficulty', 0)
+        )
+
+    def _generate_sec_cpt_answers(self, sec: str) -> List[str]:
+        answers = []
+        difficulty = self.challenge_data.difficulty
+
+        while True:
+            answer = f"0.{os.urandom(8).hex()}"
+            hash_input = f"{sec}{self.challenge_data.timestamp}{self.challenge_data.nonce}{difficulty}{answer}"
+
+            output = 0
+            for byte in hashlib.sha256(hash_input.encode('ascii')).digest():
+                output = (output << 8) | byte
+                output %= difficulty
+
+            if output == 0:
+                difficulty += 1
+                answers.append(answer)
+
+                if len(answers) == 10:
+                    break
+                continue
+
+        return answers

hyper_sdk-0.1.0/hyper_sdk/akamai/stop_signal.py

@@ -0,0 +1,52 @@
+def is_cookie_valid(cookie: str, request_count: int) -> bool:
+    """
+        Determines if the provided _abck cookie value is valid, based on Akamai Bot Manager's
+        client-side stop signal mechanism using the given request count. If the result is true, the client is ADVISED
+        to halt further sensor data submissions. Submitting further would still produce a valid cookie but is unnecessary.
+
+        The stop signal mechanism in the Akamai Bot Manager's client-side script informs a client that the cookie received is
+        valid and that any additional submissions are superfluous.
+
+        Args:
+            cookie (str): The _abck cookie value.
+            request_count (int): The number of requests made.
+
+        Returns:
+            bool: True if the cookie is valid, False otherwise.
+    """
+    parts = cookie.split("~")
+    if len(parts) < 2:
+        return False
+
+    try:
+        request_threshold = int(parts[1])
+    except ValueError:
+        request_threshold = -1
+
+    return request_threshold != -1 and request_count >= request_threshold
+
+
+def is_cookie_invalidated(cookie: str) -> bool:
+    """
+        Determines if the current session requires more sensors to be sent.
+
+        Protected endpoints can invalidate a session by setting a new _abck cookie that ends in '~0~-1~-1' or similar.
+        This function returns if such an invalidated cookie is present, if it is present you should be able to make the
+        cookie valid again with only 1 sensor post.
+
+        Args:
+            cookie (str): The _abck cookie value.
+
+        Returns:
+            bool: True if the cookie has been invalidated, False otherwise.
+    """
+    parts = cookie.split("~")
+    if len(parts) < 4:
+        return False
+
+    try:
+        signal = int(parts[3])
+    except ValueError:
+        signal = -1
+
+    return signal > -1

hyper_sdk-0.1.0/hyper_sdk/akamai_input.py

@@ -0,0 +1,15 @@
+class SensorInput:
+    def __init__(self, abck: str, bmsz: str, version: str, page_url: str, user_agent: str, script_hash=""):
+        self.abck = abck
+        self.bmsz = bmsz
+        self.version = version
+        self.page_url = page_url
+        self.user_agent = user_agent
+        self.script_hash = script_hash
+
+
+class PixelInput:
+    def __init__(self, user_agent: str, html_var: str, script_var: str):
+        self.user_agent = user_agent
+        self.html_var = html_var
+        self.script_var = script_var

hyper_sdk-0.1.0/hyper_sdk/incapsula/__init__.py

@@ -0,0 +1 @@
+from .utmvc import *

hyper_sdk-0.1.0/hyper_sdk/incapsula/utmvc.py

@@ -0,0 +1,42 @@
+import re
+import random
+
+# Precompiled regular expressions
+script_regex = re.compile(r'src="(/_Incapsula_Resource\?[^"]*)"')
+
+
+def parse_utmvc_script_path(script_content: str) -> str:
+    """
+        Parses the UTMVC script path from the given script content.
+
+        This function searches the provided script content for a specific pattern matching the UTMVC script path
+        using a precompiled regular expression. It extracts and returns the first match if found.
+
+        Args:
+            script_content (str): The content of the script from which the UTMVC script path is to be extracted.
+
+        Returns:
+            str: The extracted UTMVC script path.
+
+        Raises:
+            Exception: If the UTMVC script path is not found in the script content.
+    """
+    match = script_regex.search(script_content)
+    if match:
+        return match.group(1)
+    else:
+        raise Exception("hyper-sdk: utmvc script not found")
+
+
+def get_utmvc_submit_path() -> str:
+    """
+        Generates a UTMVC submit path with a unique random query parameter.
+
+        This function constructs a submit path for the UTMVC script by appending a random floating-point number as a query
+        parameter. The random number is used to ensure uniqueness of the request.
+
+        Returns:
+            str: A unique UTMVC submit path.
+    """
+    random_float = random.random()
+    return f"/_Incapsula_Resource?SWKMTFSR=1&e={random_float:g}"

hyper_sdk-0.1.0/hyper_sdk/incapsula_input.py

@@ -0,0 +1,5 @@
+class UtmvcInput:
+    def __init__(self, user_agent, session_ids, script):
+        self.user_agent = user_agent
+        self.session_ids = session_ids
+        self.script = script

hyper_sdk-0.1.0/hyper_sdk/session.py

@@ -0,0 +1,138 @@
+from typing import Optional, Dict, Any
+from urllib.parse import quote
+
+import requests
+import jwt
+from datetime import datetime, timedelta, timezone
+
+from .akamai_input import SensorInput, PixelInput
+from .incapsula_input import UtmvcInput
+
+
+class Session:
+    def __init__(self, api_key: str, jwt_key: Optional[str] = None, client: Optional[requests.Session] = None) -> None:
+        self.api_key = api_key
+        self.jwt_key = jwt_key
+        self.client = requests.Session() if client is None else client
+
+    def generate_sensor_data(self, input_data: SensorInput) -> str:
+        """
+            Returns the sensor data required to generate valid akamai cookies using the Hyper Solutions API.
+
+            Args:
+                input_data (SensorInput): An instance of SensorInput containing the necessary data for generating the sensor data.
+
+            Returns:
+                str: Sensor data as a string.
+        """
+        sensor_endpoint = "https://akm.justhyped.dev/sensor"
+        return self._send_request(sensor_endpoint, {
+            'userAgent': input_data.user_agent,
+            'abck': input_data.abck,
+            'bmsz': input_data.bmsz,
+            'version': input_data.version,
+            'pageUrl': input_data.page_url,
+            'scriptHash': input_data.script_hash,
+        })
+
+    def generate_pixel_data(self, input_data: PixelInput) -> str:
+        """
+            Returns the pixel data using the Hyper Solutions API.
+
+            Args:
+                session (Session): An instance of Session to handle the network request.
+                input_data (PixelInput): An instance of PixelInput containing the necessary data for generating the pixel data.
+
+            Returns:
+                str: Pixel data as a string.
+        """
+        pixel_endpoint = "https://akm.justhyped.dev/pixel"
+        return self._send_request(pixel_endpoint, {
+            'userAgent': input_data.user_agent,
+            'htmlVar': input_data.html_var,
+            'scriptVar': input_data.script_var,
+        })
+
+    def generate_reese84_sensor(self, site: str, user_agent: str) -> str:
+        """
+            Returns the sensor data required to generate valid reese84 cookies using the Hyper Solutions API.
+
+            This function sends a request to the specified sensor endpoint with the necessary data to generate the reese84 sensor data.
+
+            Args:
+                site (str): The name of the site that will be used to generate the sensor data.
+                user_agent (str): The user agent string used to generate the sensor data.
+
+            Returns:
+                str: Sensor data as a string.
+
+            Raises:
+                ValueError: If the script attribute in input_data is empty.
+        """
+        return self._send_request("https://incapsula.justhyped.dev/reese84/" + quote(site),
+                                  {
+                                      'userAgent': user_agent,
+                                  })
+
+    def generate_utmvc_cookie(self, input_data: UtmvcInput) -> str:
+        """
+            Returns the utmvc cookie using the Hyper Solutions API.
+
+            This function sends a request to the utmvc sensor endpoint with the necessary data to generate the utmvc cookie.
+            The input data must include a non-empty script and session IDs.
+
+            Args:
+                session (Session): An instance of Session to handle the network request.
+                input_data (Input): An instance of Input containing the user agent, session IDs, and script.
+
+            Returns:
+                str: The utmvc cookie as a string.
+
+            Raises:
+                ValueError: If the script attribute or session IDs in input_data are empty.
+        """
+        if not input_data.script:
+            raise ValueError("script must be non empty")
+
+        if not input_data.session_ids:
+            raise ValueError("no session ids set")
+
+        return self._send_request("https://incapsula.justhyped.dev/utmvc", {
+            'userAgent': input_data.user_agent,
+            'sessionIds': input_data.session_ids,
+            'script': input_data.script,
+        })
+
+    def generate_signature(self) -> str:
+        claims = {
+            "key": self.api_key,
+            "exp": datetime.now(timezone.utc) + timedelta(seconds=15)
+        }
+        token = jwt.encode(claims, self.jwt_key, algorithm='HS256')
+        return token.decode('utf-8')
+
+    def _send_request(self, url: str, input_data: Dict[str, Any]) -> str:
+        if not self.api_key:
+            raise ValueError("Missing API key")
+
+        headers = {
+            'Content-Type': 'application/json',
+            'Accept-Encoding': 'gzip',
+            'X-Api-Key': self.api_key
+        }
+
+        if self.jwt_key:
+            signature = self.generate_signature()
+            headers['X-Signature'] = signature
+
+        response = self.client.post(url, headers=headers, json=input_data)
+
+        response_data = response.json()
+
+        if "error" in response_data and response_data["error"]:
+            raise Exception(f"API returned with error: {response_data['error']}")
+
+        if response.status_code != 200:
+            raise Exception(f"API returned with status code: {response.status_code}")
+
+        return response_data["payload"]

hyper_sdk-0.1.0/hyper_sdk.egg-info/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.1
+Name: hyper_sdk
+Version: 0.1.0
+Summary: Hyper Solutions Python SDK
+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
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+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: requests==2.31.0
+Requires-Dist: urllib3==2.2.1
+
+# Hyper Solutions SDK for Python
+
+## Installation
+
+To use the Hyper Solutions SDK in your Python project, you need to install it using the following command:
+
+```
+pip install hyper-sdk
+```
+
+## Usage
+
+### Creating a Session
+
+To start using the SDK, you need to create a new `Session` instance by providing your API key:
+
+```python
+from hyper_sdk import Session
+
+session = Session(api_key="your-api-key")
+```
+
+You can also optionally set a JWT key and a custom HTTP client:
+
+```python
+from hyper_sdk import Session
+
+session = Session(api_key="your-api-key", jwt_key="your-jwt-key", client=custom_http_client)
+```
+
+## Akamai
+
+The Akamai package provides functions for interacting with Akamai Bot Manager, including generating sensor data, parsing script path, parsing pixel challenges, and handling sec-cpt challenges.
+
+### Generating Sensor Data
+
+To generate sensor data required for generating valid Akamai cookies, use the `generate_sensor_data` method:
+
+```python
+from hyper_sdk import SensorInput
+
+sensor_input = SensorInput(
+    page_url="https://example.com/",
+    user_agent="your-user-agent",
+    abck="your-abck-cookie",
+    bmsz="your-bmsz-cookie",
+    version="2.0"
+)
+sensor_data = session.generate_sensor_data(sensor_input)
+```
+
+### Parsing Script Path
+
+To parse the Akamai Bot Manager script path from the given HTML code, use the `parse_script_path` function from the `script_path` module:
+
+```python
+from hyper_sdk.akamai.script_path import parse_script_path
+
+script_path = parse_script_path(html_source)
+```
+
+### Handling Sec-Cpt Challenges
+
+The Akamai package provides functions for handling sec-cpt challenges:
+
+- `SecCptChallenge.parse`: Parses a sec-cpt challenge from an HTML source.
+- `generate_sec_cpt_payload`: Generates a sec-cpt payload using the provided sec-cpt cookie.
+- `update_sec_cpt_challenge_data`: Updates the challenge data of a `SecCptChallenge` instance from a response body.
+
+Example usage:
+
+```python
+from hyper_sdk.akamai.sec_cpt import SecCptChallenge
+
+challenge = SecCptChallenge.parse(html_source)
+payload = challenge.generate_sec_cpt_payload(sec_cpt_cookie)
+challenge.update_sec_cpt_challenge_data(response_body)
+```
+
+### Validating Cookies
+
+The Akamai package provides functions for validating cookies:
+
+- `is_cookie_valid`: Determines if the provided `_abck` cookie value is valid based on the given request count.
+- `is_cookie_invalidated`: Determines if the current session requires more sensors to be sent.
+
+Example usage:
+
+```python
+from hyper_sdk.akamai.stop_signal import is_cookie_valid, is_cookie_invalidated
+
+is_valid = is_cookie_valid(abck_cookie, request_count)
+is_invalidated = is_cookie_invalidated(abck_cookie)
+```
+
+### Generating Pixel Data
+
+To generate pixel data, use the `generate_pixel_data` method:
+
+```python
+from hyper_sdk import PixelInput
+
+pixel_input = PixelInput(
+    user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/93.0.4577.82 Safari/537.36",
+    html_var="your-html-var",
+    script_var="your-script-var"
+)
+pixel_data = session.generate_pixel_data(pixel_input)
+```
+
+### Parsing Pixel Challenges
+
+The Akamai package provides functions for parsing pixel challenges:
+
+- `parse_pixel_html_var`: Parses the required pixel challenge variable from the given HTML code.
+- `parse_pixel_script_url`: Parses the script URL of the pixel challenge script and the URL to post a generated payload to from the given HTML code.
+- `parse_pixel_script_var`: Parses the dynamic value from the pixel script.
+
+Example usage:
+
+```python
+from hyper_sdk.akamai.pixel import parse_pixel_html_var, parse_pixel_script_url, parse_pixel_script_var
+
+html_var = parse_pixel_html_var(html_source)
+script_url, post_url = parse_pixel_script_url(html_source)
+script_var = parse_pixel_script_var(script_source)
+```
+
+
+## Incapsula
+
+The Incapsula package provides functions for interacting with Imperva Incapsula, including generating Reese84 sensor data, UTMVC cookies, and parsing UTMVC script paths.
+
+### Generating Reese84 Sensor
+
+To generate sensor data required for generating valid Reese84 cookies, use the `generate_reese84_sensor` method:
+
+```python
+sensor_data = session.generate_reese84_sensor(site="example.com", user_agent="your-user-agent")
+```
+
+### Generating UTMVC Cookie
+
+To generate the UTMVC cookie using the Hyper Solutions API, use the `generate_utmvc_cookie` method:
+
+```python
+from hyper_sdk import UtmvcInput
+
+utmvc_input = UtmvcInput(
+    user_agent="your-user-agent",
+    session_ids=["session-id-1", "session-id-2"],
+    script="your-script"
+)
+utmvc_cookie = session.generate_utmvc_cookie(utmvc_input)
+```
+
+### Parsing UTMVC Script Path
+
+To parse the UTMVC script path from a given script content, use the `parse_utmvc_script_path` function from the `utmvc` module:
+
+```python
+from hyper_sdk.incapsula.utmvc import parse_utmvc_script_path
+
+script_path = parse_utmvc_script_path(script_content)
+```
+
+### Generating UTMVC Submit Path
+
+To generate a unique UTMVC submit path with a random query parameter, use the `get_utmvc_submit_path` function from the `utmvc` module:
+
+```python
+from hyper_sdk.incapsula.utmvc import get_utmvc_submit_path
+
+submit_path = get_utmvc_submit_path()
+```

hyper_sdk-0.1.0/hyper_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+hyper_sdk/__init__.py
+hyper_sdk/akamai_input.py
+hyper_sdk/incapsula_input.py
+hyper_sdk/session.py
+hyper_sdk.egg-info/PKG-INFO
+hyper_sdk.egg-info/SOURCES.txt
+hyper_sdk.egg-info/dependency_links.txt
+hyper_sdk.egg-info/requires.txt
+hyper_sdk.egg-info/top_level.txt
+hyper_sdk/akamai/__init__.py
+hyper_sdk/akamai/pixel.py
+hyper_sdk/akamai/script_path.py
+hyper_sdk/akamai/sec_cpt.py
+hyper_sdk/akamai/stop_signal.py
+hyper_sdk/incapsula/__init__.py
+hyper_sdk/incapsula/utmvc.py

hyper_sdk-0.1.0/hyper_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hyper_sdk-0.1.0/hyper_sdk.egg-info/requires.txt

@@ -0,0 +1,7 @@
+certifi==2024.2.2
+charset-normalizer==3.3.2
+idna==3.6
+jsonpickle==3.0.3
+PyJWT==2.8.0
+requests==2.31.0
+urllib3==2.2.1

hyper_sdk-0.1.0/hyper_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+hyper_sdk

hyper_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hyper_sdk"
+version = "0.1.0"
+description = "Hyper Solutions Python SDK"
+readme = "README.md"
+requires-python = ">=3.6"
+classifiers = [
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "certifi==2024.2.2",
+    "charset-normalizer==3.3.2",
+    "idna==3.6",
+    "jsonpickle==3.0.3",
+    "PyJWT==2.8.0",
+    "requests==2.31.0",
+    "urllib3==2.2.1",
+]
+
+[project.urls]
+homepage = "https://github.com/Hyper-Solutions/hyper-sdk-py"
+
+[tool.setuptools]
+packages = ["hyper_sdk", "hyper_sdk.akamai", "hyper_sdk.incapsula"]

hyper_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+