### Full Humble Bundle Workflow Example

Source: https://context7.com/saik0/humblebundle-python/llms.txt

Demonstrates a complete workflow including client initialization, store search, user authentication, retrieving and processing all purchase orders, and accessing download information for different platforms. It also shows how to manage session cookies for persistence.

```python
import humblebundle
from humblebundle.exceptions import HumbleAuthenticationException

# Initialize client
client = humblebundle.HumbleApi()

# Search store (no auth required)
results = client.search_store("indie")
print(f"Found {len(results)} store items")

# Login to access purchases
client.login("username@example.com", "secret")

# Get all order identifiers
order_list = client.get_gamekeys()
print(f"Found {len(order_list)} orders")

# Process each order
for gamekey in order_list:
    order = client.get_order(gamekey)

    print(f"\nBundle: {order.product.human_name}")

    if order.subproducts:
        for subproduct in order.subproducts:
            print(f"  {subproduct.human_name}")

            # List available downloads per platform
            for download in subproduct.downloads:
                platform = download.platform
                version = download.download_version_number

                for struct in download.download_struct:
                    if struct.url.web:
                        print(f"    [{platform}] {struct.name} ({struct.human_size})")

# Access session cookies for persistence
cookies = client.session.cookies
# Save cookies to file or database for later use

# Restore session later
# client.session.cookies = loaded_cookies
```

--------------------------------

### GET /api/v1/store/search - Search Humble Bundle Store

Source: https://context7.com/saik0/humblebundle-python/llms.txt

Searches the Humble Bundle store for products. This operation does not require user authentication.

```APIDOC
## GET /api/v1/store/search - Search Humble Bundle Store

Searches the Humble Bundle store for products. Does not require authentication.

### Method
GET

### Endpoint
/api/v1/store/search

### Parameters
#### Query Parameters
- **query** (string) - Required - The search term for products.

### Request Example
```python
import humblebundle

client = humblebundle.HumbleApi()

# Search for games (no login required)
results = client.search_store("FTL")

for product in results:
    print(f"Name: {product.human_name}")
    print(f"Machine Name: {product.machine_name}")
    print(f"Price: {product.current_price.value:.2f} {product.current_price.currency}")
    print(f"Full Price: {product.full_price.value:.2f} {product.full_price.currency}")
    print(f"Platforms: {product.platforms}")
    print(f"Delivery: {product.delivery_methods}")  # download, steam, origin
    print(f"ESRB: {product.esrb_rating}")
    print("---")

# StoreProduct attributes available:
# - human_name, machine_name
# - current_price, full_price (Price objects with .value and .currency)
# - icon (URL string)
# - platforms (linux, windows, mac)
# - delivery_methods (download, steam, origin)
# - description (HTML)
# - developers, publishers
# - system_requirements (HTML)
```

### Response
#### Success Response (200)
- **results** (array) - A list of product objects matching the search query.
  - Each product object contains attributes like `human_name`, `machine_name`, `current_price`, `full_price`, `platforms`, `delivery_methods`, `esrb_rating`, `icon`, `description`, `developers`, `publishers`, and `system_requirements`.
```

--------------------------------

### GET /api/v1/claimed-entities

Source: https://context7.com/saik0/humblebundle-python/llms.txt

Downloads all claimed entities for the authenticated user. This call can be slow as it collects extensive purchase data.

```APIDOC
## GET /api/v1/claimed-entities

### Description
Downloads all claimed entities for the authenticated user. This call can be slow as it collects extensive purchase data.

### Method
GET

### Endpoint
/api/v1/claimed-entities

### Parameters
#### Path Parameters
None

#### Query Parameters
- **platform** (string) - Optional - Filters the claimed entities by platform. Valid platforms: android, audio, ebook, linux, mac, windows.

#### Request Body
None

### Request Example
```python
import humblebundle
from humblebundle.exceptions import HumbleException

client = humblebundle.HumbleApi()
client.login("username@example.com", "password123")

# Get all claimed entities (returns raw JSON dict)
entities = client.get_claimed_entities()
print(entities)

# Filter by platform
try:
    android_entities = client.get_claimed_entities(platform="android")
    linux_entities = client.get_claimed_entities(platform="linux")
    ebooks = client.get_claimed_entities(platform="ebook")

except HumbleException as e:
    print(f"Unsupported platform: {e}")
```

### Response
#### Success Response (200)
- **entities** (object) - A dictionary containing claimed entities, potentially filtered by platform.

#### Response Example
```json
{
  "android": [
    {
      "product": {
        "human_name": "Android Game",
        "machine_name": "androidgame"
      },
      "order_id": "123456789"
    }
  ],
  "ebook": [
    {
      "product": {
        "human_name": "Ebook Title",
        "machine_name": "ebooktitle"
      },
      "order_id": "987654321"
    }
  ]
}
```

### Notes
This method has a 60-second default timeout due to potentially slow server responses.
```

--------------------------------

### GET /api/v1/users/me/keys - Retrieve All Order Keys

Source: https://context7.com/saik0/humblebundle-python/llms.txt

Fetches all gamekeys (order identifiers) owned by the authenticated account. Requires the user to be logged in.

```APIDOC
## GET /api/v1/users/me/keys - Retrieve All Order Keys

Fetches all gamekeys (order identifiers) owned by the authenticated account.

### Method
GET

### Endpoint
/api/v1/users/me/keys

### Parameters
Requires authentication. The user must be logged in via the `login` method.

### Request Example
```python
import humblebundle
from humblebundle.exceptions import HumbleAuthenticationException

client = humblebundle.HumbleApi()
client.login("username@example.com", "password123")

try:
    gamekeys = client.get_gamekeys()

    print(f"Found {len(gamekeys)} orders")
    for gamekey in gamekeys:
        print(f"Gamekey: {gamekey}")
        # Output: Gamekey: AbCdEfGhIjKl123

except HumbleAuthenticationException as e:
    print(f"Not logged in: {e}")
```

### Response
#### Success Response (200)
- **gamekeys** (array) - A list of strings, where each string is a gamekey (order identifier).
```

--------------------------------

### GET /api/v1/order/{order_id}

Source: https://context7.com/saik0/humblebundle-python/llms.txt

Retrieve detailed information about a specific order, including all subproducts (games, ebooks, etc.).

```APIDOC
## GET /api/v1/order/{order_id}

### Description
Retrieves detailed information about a specific order including all subproducts (games, ebooks, etc.).

### Method
GET

### Endpoint
/api/v1/order/{order_id}

### Parameters
#### Path Parameters
- **order_id** (string) - Required - The unique identifier for the order.

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import humblebundle

client = humblebundle.HumbleApi()
client.login("username@example.com", "password123")

# Assuming gamekeys is a list of order IDs
gamekeys = client.get_gamekeys()
order = client.get_order(gamekeys[0])

print(f"Order: {order.product.human_name}")
print(f"Machine Name: {order.product.machine_name}")
print(f"Claimed: {order.claimed}")
print(f"Country: {order.country}")
print(f"Platform: {order.platform}")

if order.subproducts:
    for subproduct in order.subproducts:
        print(f"  - {subproduct.human_name}")
        print(f"    Machine: {subproduct.machine_name}")
        print(f"    URL: {subproduct.url}")
        print(f"    Payee: {subproduct.payee.human_name}")

        for download in subproduct.downloads:
            print(f"    Platform: {download.platform}")
            print(f"    Version: {download.download_version_number}")

            for struct in download.download_struct:
                print(f"      File: {struct.name}")
                print(f"      Size: {struct.human_size}")
                print(f"      URL: {struct.url.web}")
                print(f"      SHA1: {struct.sha1}")
```

### Response
#### Success Response (200)
- **product** (object) - Information about the main product in the order.
- **claimed** (boolean) - Indicates if the order has been claimed.
- **country** (string) - The country associated with the order.
- **platform** (string) - The platform of the order.
- **subproducts** (array) - A list of subproducts included in the order.
  - **human_name** (string) - Human-readable name of the subproduct.
  - **machine_name** (string) - Machine-readable name of the subproduct.
  - **url** (string) - URL for the subproduct.
  - **payee** (object) - Information about the payee.
    - **human_name** (string) - Human-readable name of the payee.
  - **downloads** (array) - List of available downloads for the subproduct.
    - **platform** (string) - The platform for the download.
    - **download_version_number** (string) - The version number of the download.
    - **download_struct** (array) - Structure of the download files.
      - **name** (string) - Name of the file.
      - **human_size** (string) - Human-readable size of the file.
      - **url** (object) - URLs for the download.
        - **web** (string) - Web URL for the download.
      - **sha1** (string) - SHA1 hash of the file.

#### Response Example
```json
{
  "product": {
    "human_name": "Humble Bundle",
    "machine_name": "humble_bundle"
  },
  "claimed": true,
  "country": "US",
  "platform": "windows",
  "subproducts": [
    {
      "human_name": "Game Title",
      "machine_name": "gametitle_windows",
      "url": "http://www.humblebundle.com/store/gametitle",
      "payee": {
        "human_name": "Developer Name"
      },
      "downloads": [
        {
          "platform": "windows",
          "download_version_number": "1.0",
          "download_struct": [
            {
              "name": "gametitle_setup.exe",
              "human_size": "1.5 GB",
              "url": {
                "web": "http://humblebundle.com/download/gametitle/windows/1.0/gametitle_setup.exe"
              },
              "sha1": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4"
            }
          ]
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Initialize HumbleApi Client

Source: https://context7.com/saik0/humblebundle-python/llms.txt

Creates a new API client instance with default headers mimicking the Android app client.

```python
import humblebundle

# Create a new API client instance
client = humblebundle.HumbleApi()

# The client maintains a requests.Session internally
# Default headers include:
# - Accept: application/json
# - X-Requested-By: hb_android_app
# - User-Agent: Apache-HttpClient/UNAVAILABLE (java 1.4)
```

--------------------------------

### Query Humble Bundle API

Source: https://github.com/saik0/humblebundle-python/blob/master/README.rst

Initializes the API client to search the store, authenticate, and iterate through order subproducts.

```python
client = humblebundle.HumbleApi()

client.search_store("ftl")

client.login("username@example.com", "secret")

gamekeys = client.get_gamekeys()

for gamekey in gamekeys:
    order = client.get_order(gamekey)
    for subproduct in order.subproducts:
        print(subproduct)
```

--------------------------------

### HumbleApi Client Initialization

Source: https://context7.com/saik0/humblebundle-python/llms.txt

Initializes the HumbleApi client, which manages sessions and handles authentication for interacting with the Humble Bundle API. It sets default headers to mimic the Android app client.

```APIDOC
## HumbleApi Client Initialization

The main entry point for interacting with the Humble Bundle API. Creates a session with default headers that mimic the Android app client.

### Request Example
```python
import humblebundle

# Create a new API client instance
client = humblebundle.HumbleApi()

# The client maintains a requests.Session internally
# Default headers include:
# - Accept: application/json
# - X-Requested-By: hb_android_app
# - User-Agent: Apache-HttpClient/UNAVAILABLE (java 1.4)
```
```

--------------------------------

### Search Humble Bundle Store

Source: https://context7.com/saik0/humblebundle-python/llms.txt

Queries the store for products without requiring authentication.

```python
import humblebundle

client = humblebundle.HumbleApi()

# Search for games (no login required)
results = client.search_store("FTL")

for product in results:
    print(f"Name: {product.human_name}")
    print(f"Machine Name: {product.machine_name}")
    print(f"Price: {product.current_price.value:.2f} {product.current_price.currency}")
    print(f"Full Price: {product.full_price.value:.2f} {product.full_price.currency}")
    print(f"Platforms: {product.platforms}")
    print(f"Delivery: {product.delivery_methods}")  # download, steam, origin
    print(f"ESRB: {product.esrb_rating}")
    print("---")

# StoreProduct attributes available:
# - human_name, machine_name
# - current_price, full_price (Price objects with .value and .currency)
# - icon (URL string)
# - platforms (linux, windows, mac)
# - delivery_methods (download, steam, origin)
# - description (HTML)
# - developers, publishers
# - system_requirements (HTML)
```

--------------------------------

### Retrieve Order Details with Humble Bundle API

Source: https://context7.com/saik0/humblebundle-python/llms.txt

Downloads detailed information about a specific order, including all subproducts like games and ebooks. Requires prior login and fetching game keys.

```python
import humblebundle

client = humblebundle.HumbleApi()
client.login("username@example.com", "password123")

gamekeys = client.get_gamekeys()

for gamekey in gamekeys:
    order = client.get_order(gamekey)

    print(f"Order: {order.product.human_name}")
    print(f"Machine Name: {order.product.machine_name}")
    print(f"Claimed: {order.claimed}")
    print(f"Country: {order.country}")
    print(f"Platform: {order.platform}")

    # Iterate through all items in the order
    if order.subproducts:
        for subproduct in order.subproducts:
            print(f"  - {subproduct.human_name}")
            print(f"    Machine: {subproduct.machine_name}")
            print(f"    URL: {subproduct.url}")
            print(f"    Payee: {subproduct.payee.human_name}")

            # Get downloads for each platform
            for download in subproduct.downloads:
                print(f"    Platform: {download.platform}")
                print(f"    Version: {download.download_version_number}")

                for struct in download.download_struct:
                    print(f"      File: {struct.name}")
                    print(f"      Size: {struct.human_size}")
                    print(f"      URL: {struct.url.web}")
                    print(f"      SHA1: {struct.sha1}")
    print("---")
```

--------------------------------

### Generate Signed Download URL with Humble Bundle API

Source: https://context7.com/saik0/humblebundle-python/llms.txt

Generates a signed download URL for a specific subproduct by its machine name. Can be obtained directly or from a Download object. Note: This API returns the first download in the list.

```python
import humblebundle

client = humblebundle.HumbleApi()
client.login("username@example.com", "password123")

# Get signed URL directly from client
signed_url = client.sign_download_url("ftlgame_linux")
print(f"Download URL: {signed_url}")

# Or get it from a Download object
gamekeys = client.get_gamekeys()
order = client.get_order(gamekeys[0])

if order.subproducts:
    for subproduct in order.subproducts:
        for download in subproduct.downloads:
            # Sign URL via the Download model method
            url = download.sign_download_url()
            print(f"{download.machine_name}: {url}")

# Note: This API always returns the first download in the list,
# making it less useful for platforms with multiple download options
```

--------------------------------

### Handle Humble Bundle API Exceptions

Source: https://context7.com/saik0/humblebundle-python/llms.txt

Demonstrates comprehensive exception handling for various Humble Bundle API error scenarios, including authentication, CAPTCHA, two-factor, parsing, and general response errors. Also includes handling for network-related RequestExceptions.

```python
import humblebundle
from humblebundle.exceptions import (
    HumbleException,
    HumbleResponseException,
    HumbleAuthenticationException,
    HumbleCredentialException,
    HumbleCaptchaException,
    HumbleTwoFactorException,
    HumbleParseException
)
from requests import RequestException

client = humblebundle.HumbleApi()

try:
    client.login("user@example.com", "password")
    gamekeys = client.get_gamekeys()

    for gamekey in gamekeys:
        order = client.get_order(gamekey)
        print(order.product.human_name)

except HumbleCredentialException as e:
    # Username/password mismatch
    print(f"Invalid credentials: {e}")

except HumbleCaptchaException as e:
    # CAPTCHA verification failed
    print(f"CAPTCHA error: {e}")
    print(f"Captcha required: {e.captcha_required}")

except HumbleTwoFactorException as e:
    # Two-factor auth token invalid
    print(f"2FA error: {e}")
    print(f"Authy required: {e.authy_required}")

except HumbleAuthenticationException as e:
    # General auth failure (not logged in)
    print(f"Auth error: {e}")

except HumbleParseException as e:
    # Invalid JSON response
    print(f"Parse error: {e}")

except HumbleResponseException as e:
    # Unexpected API response
    print(f"Response error: {e}")

except RequestException as e:
    # Network/connection error
    print(f"Connection error: {e}")

except HumbleException as e:
    # Base exception for all Humble errors
    print(f"Humble error: {e}")
```

--------------------------------

### POST /api/v1/user/login - Authenticate with Humble Bundle

Source: https://context7.com/saik0/humblebundle-python/llms.txt

Authenticates the user with Humble Bundle credentials and stores the session cookie for subsequent API calls. Supports basic authentication, CAPTCHA solving, and two-factor authentication.

```APIDOC
## POST /api/v1/user/login - Authenticate with Humble Bundle

Authenticates the user and stores the session cookie for subsequent API calls. Supports two-factor authentication via Authy/Google Authenticator.

### Method
POST

### Endpoint
/api/v1/user/login

### Parameters
#### Request Body
- **username** (string) - Required - The user's Humble Bundle username or email.
- **password** (string) - Required - The user's Humble Bundle password.
- **recaptcha_challenge** (string) - Optional - The challenge string for CAPTCHA solving.
- **recaptcha_response** (string) - Optional - The solved CAPTCHA response.
- **authy_token** (string) - Optional - The 6-digit 2FA token from an authenticator app.

### Request Example
```python
import humblebundle
from humblebundle.exceptions import (
    HumbleCredentialException,
    HumbleCaptchaException,
    HumbleTwoFactorException
)

client = humblebundle.HumbleApi()

try:
    # Basic login
    client.login("username@example.com", "password123")
    print("Login successful!")

except HumbleCredentialException as e:
    print(f"Invalid username or password: {e}")

except HumbleCaptchaException as e:
    # CAPTCHA required - need to solve and retry
    print("CAPTCHA required")
    client.login(
        "username@example.com",
        "password123",
        recaptcha_challenge="challenge_from_humble",
        recaptcha_response="solved_captcha_text"
    )

except HumbleTwoFactorException as e:
    # Two-factor authentication required
    print("2FA token required")
    client.login(
        "username@example.com",
        "password123",
        authy_token="123456"  # 6-digit code from authenticator app
    )
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the login was successful.

#### Error Response
- **error** (string) - Description of the error (e.g., invalid credentials, CAPTCHA required, 2FA required).
```

--------------------------------

### Authenticate with Humble Bundle

Source: https://context7.com/saik0/humblebundle-python/llms.txt

Authenticates the user and handles CAPTCHA or two-factor authentication requirements.

```python
import humblebundle
from humblebundle.exceptions import (
    HumbleCredentialException,
    HumbleCaptchaException,
    HumbleTwoFactorException
)

client = humblebundle.HumbleApi()

try:
    # Basic login
    client.login("username@example.com", "password123")
    print("Login successful!")

except HumbleCredentialException as e:
    print(f"Invalid username or password: {e}")

except HumbleCaptchaException as e:
    # CAPTCHA required - need to solve and retry
    print("CAPTCHA required")
    client.login(
        "username@example.com",
        "password123",
        recaptcha_challenge="challenge_from_humble",
        recaptcha_response="solved_captcha_text"
    )

except HumbleTwoFactorException as e:
    # Two-factor authentication required
    print("2FA token required")
    client.login(
        "username@example.com",
        "password123",
        authy_token="123456"  # 6-digit code from authenticator app
    )
```

--------------------------------

### Retrieve All Order Keys

Source: https://context7.com/saik0/humblebundle-python/llms.txt

Fetches all gamekeys associated with the authenticated user account.

```python
import humblebundle
from humblebundle.exceptions import HumbleAuthenticationException

client = humblebundle.HumbleApi()
client.login("username@example.com", "password123")

try:
    gamekeys = client.get_gamekeys()

    print(f"Found {len(gamekeys)} orders")
    for gamekey in gamekeys:
        print(f"Gamekey: {gamekey}")
        # Output: Gamekey: AbCdEfGhIjKl123

except HumbleAuthenticationException as e:
    print(f"Not logged in: {e}")
```

--------------------------------

### Retrieve All Claimed Entities with Humble Bundle API

Source: https://context7.com/saik0/humblebundle-python/llms.txt

Downloads all claimed entities for the authenticated user. This call can be slow due to extensive data collection. Supports filtering by platform.

```python
import humblebundle
from humblebundle.exceptions import HumbleException

client = humblebundle.HumbleApi()
client.login("username@example.com", "password123")

# Get all claimed entities (returns raw JSON dict)
entities = client.get_claimed_entities()
print(entities)

# Filter by platform
try:
    # Valid platforms: android, audio, ebook, linux, mac, windows
    android_entities = client.get_claimed_entities(platform="android")
    linux_entities = client.get_claimed_entities(platform="linux")
    ebooks = client.get_claimed_entities(platform="ebook")

except HumbleException as e:
    print(f"Unsupported platform: {e}")

# Note: This method has a 60-second default timeout due to slow server response
```

--------------------------------

### Utilize Callback Pattern in Humble Bundle API

Source: https://context7.com/saik0/humblebundle-python/llms.txt

All API methods support an optional callback parameter for processing results asynchronously. Callbacks can be defined for various API calls.

```python
import humblebundle

client = humblebundle.HumbleApi()
client.login("username@example.com", "password123")

# Define a callback function
def process_gamekeys(gamekeys):
    print(f"Processing {len(gamekeys)} gamekeys")
    for key in gamekeys:
        print(f"  - {key}")

# Pass callback to API method
client.get_gamekeys(callback=process_gamekeys)

# Callbacks work on all API methods
def process_order(order):
    print(f"Order: {order.product.human_name}")
    if order.subproducts:
        for sp in order.subproducts:
            print(f"  Item: {sp.human_name}")

gamekeys = client.get_gamekeys()
client.get_order(gamekeys[0], callback=process_order)
```

--------------------------------

### POST /api/v1/download/sign

Source: https://context7.com/saik0/humblebundle-python/llms.txt

Generates a signed download URL for a specific subproduct by its machine name.

```APIDOC
## POST /api/v1/download/sign

### Description
Generates a signed download URL for a specific subproduct by its machine name.

### Method
POST

### Endpoint
/api/v1/download/sign

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **machine_name** (string) - Required - The machine name of the subproduct for which to generate a signed URL.

### Request Example
```python
import humblebundle

client = humblebundle.HumbleApi()
client.login("username@example.com", "password123")

# Get signed URL directly from client
signed_url = client.sign_download_url("ftlgame_linux")
print(f"Download URL: {signed_url}")

# Or get it from a Download object
gamekeys = client.get_gamekeys()
order = client.get_order(gamekeys[0])

if order.subproducts:
    for subproduct in order.subproducts:
        for download in subproduct.downloads:
            # Sign URL via the Download model method
            url = download.sign_download_url()
            print(f"{download.machine_name}: {url}")
```

### Response
#### Success Response (200)
- **signed_url** (string) - The generated signed download URL.

#### Response Example
```json
{
  "signed_url": "https://humblebundle.com/download?key=abcdef1234567890"
}
```

### Notes
This API always returns the first download in the list, making it less useful for platforms with multiple download options.
```

--------------------------------

### Callback Pattern

Source: https://context7.com/saik0/humblebundle-python/llms.txt

All API methods support an optional callback parameter for processing results asynchronously.

```APIDOC
## Callback Pattern

### Description
All API methods support an optional callback parameter for processing results. This allows for asynchronous handling of API responses.

### Method
Any (GET, POST, etc.)

### Endpoint
N/A (Applies to all endpoints)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import humblebundle

client = humblebundle.HumbleApi()
client.login("username@example.com", "password123")

# Define a callback function for get_gamekeys
def process_gamekeys(gamekeys):
    print(f"Processing {len(gamekeys)} gamekeys")
    for key in gamekeys:
        print(f"  - {key}")

# Pass callback to API method
client.get_gamekeys(callback=process_gamekeys)

# Define a callback function for get_order
def process_order(order):
    print(f"Order: {order.product.human_name}")
    if order.subproducts:
        for sp in order.subproducts:
            print(f"  Item: {sp.human_name}")

gamekeys = client.get_gamekeys()
client.get_order(gamekeys[0], callback=process_order)
```

### Response
Callbacks do not directly return a value. They process the API response data as defined within the callback function.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.