productinformationapi 0.1.0__tar.gz

productinformationapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HustleGotReal
+
+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.

productinformationapi-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: productinformationapi
+Version: 0.1.0
+Summary: Product information and stock checks with Product Information API
+Author-email: HustleGotReal <contact@hustlegotreal.com>
+License-Expression: MIT
+Project-URL: Homepage, https://productinformationapi.com
+Keywords: product-information,stock,scraping,api,sdk
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Product Information API for Python
+
+Product information and stock checks in Python 3.11+, with type hints and no runtime dependencies.
+
+## Install
+
+```sh
+python -m pip install productinformationapi
+```
+
+Or install the distributed wheel with `python -m pip install ./productinformationapi-0.1.0-py3-none-any.whl`.
+
+## Quick start
+
+Use a tenant API key from your Product Information API account. MCP OAuth access tokens are scoped
+to MCP and cannot authenticate these REST requests. Keep the key in your server environment:
+
+```sh
+export PRODUCTINFORMATIONAPI_API_KEY='your-api-key'
+```
+
+```python
+from productinformationapi import ProductInformationAPI
+
+client = ProductInformationAPI()  # Reads PRODUCTINFORMATIONAPI_API_KEY.
+url = "https://www.amazon.com/dp/B0D3BCR3V7"
+
+product = client.get_product_information(url)
+print((product.get("productInformation") or {}).get("title"), product["creditsCharged"])
+
+stock = client.check_stock(url)
+print(stock["inStock"], stock["offers"], stock["creditsRemaining"])
+```
+
+Methods return the complete API response as a dictionary. Response keys retain the API's camelCase
+names. The client is synchronous; in an asyncio application, use a worker thread:
+
+```python
+import asyncio
+
+stock = await asyncio.to_thread(client.check_stock, url)
+```
+
+Cancelling the asyncio waiter does not cancel the worker thread's HTTP request; its socket timeout
+still applies.
+
+## Bulk
+
+```python
+batch = client.check_stock_bulk([
+    "https://www.amazon.com/dp/B0D3BCR3V7",
+    {"productUrl": "https://www.amazon.co.uk/dp/B0D3BCR3V7", "sourceSite": "amazon_gb"},
+])
+
+for row in batch["results"]:
+    if row["httpStatus"] == 200:
+        print(row["index"], row["result"])
+    else:
+        print(row["index"], row["httpStatus"], row["result"]["error"])
+
+# Product information uses the same inputs:
+products = client.get_product_information_bulk([
+    "https://www.amazon.com/dp/B0D3BCR3V7",
+])
+```
+
+Bulk calls return inline. A successful HTTP response can contain failed items; inspect each
+`httpStatus`. The current default server limit is 100 items per batch. Items are never silently
+split, retried, or reordered. Large batches may require a longer HTTP timeout.
+
+## Options and errors
+
+```python
+from uuid import uuid4
+from productinformationapi import APIError
+
+request_key = str(uuid4())  # Retain this key if you retry this exact request.
+try:
+    stock = client.check_stock(
+        url,
+        idempotency_key=request_key,
+        timeout=120,
+        request_timeout_ms=30_000,
+    )
+    print(stock["inStock"])
+except APIError as error:
+    print(error.status, error.code, error.request_id, error.retry_after_s)
+```
+
+- Constructor: `ProductInformationAPI(api_key=None, *, base_url="https://api.productinformationapi.com", timeout=120)`.
+- All methods accept `idempotency_key` and `timeout` in seconds. `timeout` is the standard-library
+  socket timeout for blocking operations, not a guaranteed total wall-clock deadline.
+- Singular methods accept `source_site`. `get_product_information` also accepts
+  `include_gpsr=True` for Amazon DE GPSR details. Bulk requests do not accept GPSR options.
+- `request_timeout_ms` applies only to singular stock requests, from 1000 to 100000 milliseconds.
+  It shortens the server execution budget. Leave additional time in `timeout` for server cleanup.
+- Timeouts do not prove the server did no work or charged no credits. There are no automatic
+  retries. Reuse an idempotency key only for the same operation and payload; keep bulk items in
+  the same order on a retry. Keys must contain 1–255 visible ASCII characters.
+- `APIError` exposes `status`, `code`, `request_id`, `retryable`, `retry_after_s`, and the parsed
+  response as `body`. HTML edge failures still produce `APIError`. Bulk item errors remain in
+  `batch["results"]`. Transport failures retain standard-library exceptions such as `URLError`
+  and `TimeoutError`.
+
+## Webhooks
+
+Scrape-result webhooks and asynchronous jobs are not currently implemented by the API. These
+methods return the result directly; no webhook URL option is available.
+
+## Support and license
+
+Visit [Product Information API](https://productinformationapi.com) or contact
+[contact@hustlegotreal.com](mailto:contact@hustlegotreal.com).
+
+This SDK is MIT licensed. API access requires a separate account and is subject to the service's
+terms and credit usage.

productinformationapi-0.1.0/README.md

@@ -0,0 +1,116 @@
+# Product Information API for Python
+
+Product information and stock checks in Python 3.11+, with type hints and no runtime dependencies.
+
+## Install
+
+```sh
+python -m pip install productinformationapi
+```
+
+Or install the distributed wheel with `python -m pip install ./productinformationapi-0.1.0-py3-none-any.whl`.
+
+## Quick start
+
+Use a tenant API key from your Product Information API account. MCP OAuth access tokens are scoped
+to MCP and cannot authenticate these REST requests. Keep the key in your server environment:
+
+```sh
+export PRODUCTINFORMATIONAPI_API_KEY='your-api-key'
+```
+
+```python
+from productinformationapi import ProductInformationAPI
+
+client = ProductInformationAPI()  # Reads PRODUCTINFORMATIONAPI_API_KEY.
+url = "https://www.amazon.com/dp/B0D3BCR3V7"
+
+product = client.get_product_information(url)
+print((product.get("productInformation") or {}).get("title"), product["creditsCharged"])
+
+stock = client.check_stock(url)
+print(stock["inStock"], stock["offers"], stock["creditsRemaining"])
+```
+
+Methods return the complete API response as a dictionary. Response keys retain the API's camelCase
+names. The client is synchronous; in an asyncio application, use a worker thread:
+
+```python
+import asyncio
+
+stock = await asyncio.to_thread(client.check_stock, url)
+```
+
+Cancelling the asyncio waiter does not cancel the worker thread's HTTP request; its socket timeout
+still applies.
+
+## Bulk
+
+```python
+batch = client.check_stock_bulk([
+    "https://www.amazon.com/dp/B0D3BCR3V7",
+    {"productUrl": "https://www.amazon.co.uk/dp/B0D3BCR3V7", "sourceSite": "amazon_gb"},
+])
+
+for row in batch["results"]:
+    if row["httpStatus"] == 200:
+        print(row["index"], row["result"])
+    else:
+        print(row["index"], row["httpStatus"], row["result"]["error"])
+
+# Product information uses the same inputs:
+products = client.get_product_information_bulk([
+    "https://www.amazon.com/dp/B0D3BCR3V7",
+])
+```
+
+Bulk calls return inline. A successful HTTP response can contain failed items; inspect each
+`httpStatus`. The current default server limit is 100 items per batch. Items are never silently
+split, retried, or reordered. Large batches may require a longer HTTP timeout.
+
+## Options and errors
+
+```python
+from uuid import uuid4
+from productinformationapi import APIError
+
+request_key = str(uuid4())  # Retain this key if you retry this exact request.
+try:
+    stock = client.check_stock(
+        url,
+        idempotency_key=request_key,
+        timeout=120,
+        request_timeout_ms=30_000,
+    )
+    print(stock["inStock"])
+except APIError as error:
+    print(error.status, error.code, error.request_id, error.retry_after_s)
+```
+
+- Constructor: `ProductInformationAPI(api_key=None, *, base_url="https://api.productinformationapi.com", timeout=120)`.
+- All methods accept `idempotency_key` and `timeout` in seconds. `timeout` is the standard-library
+  socket timeout for blocking operations, not a guaranteed total wall-clock deadline.
+- Singular methods accept `source_site`. `get_product_information` also accepts
+  `include_gpsr=True` for Amazon DE GPSR details. Bulk requests do not accept GPSR options.
+- `request_timeout_ms` applies only to singular stock requests, from 1000 to 100000 milliseconds.
+  It shortens the server execution budget. Leave additional time in `timeout` for server cleanup.
+- Timeouts do not prove the server did no work or charged no credits. There are no automatic
+  retries. Reuse an idempotency key only for the same operation and payload; keep bulk items in
+  the same order on a retry. Keys must contain 1–255 visible ASCII characters.
+- `APIError` exposes `status`, `code`, `request_id`, `retryable`, `retry_after_s`, and the parsed
+  response as `body`. HTML edge failures still produce `APIError`. Bulk item errors remain in
+  `batch["results"]`. Transport failures retain standard-library exceptions such as `URLError`
+  and `TimeoutError`.
+
+## Webhooks
+
+Scrape-result webhooks and asynchronous jobs are not currently implemented by the API. These
+methods return the result directly; no webhook URL option is available.
+
+## Support and license
+
+Visit [Product Information API](https://productinformationapi.com) or contact
+[contact@hustlegotreal.com](mailto:contact@hustlegotreal.com).
+
+This SDK is MIT licensed. API access requires a separate account and is subject to the service's
+terms and credit usage.

productinformationapi-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "productinformationapi"
+version = "0.1.0"
+description = "Product information and stock checks with Product Information API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "HustleGotReal", email = "contact@hustlegotreal.com"}]
+keywords = ["product-information", "stock", "scraping", "api", "sdk"]
+classifiers = [
+    "Programming Language :: Python :: 3 :: Only",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+requires-python = ">=3.11"
+dependencies = []
+
+[project.urls]
+Homepage = "https://productinformationapi.com"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+productinformationapi = ["py.typed"]
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E501"]

productinformationapi-0.1.0/setup.cfg

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

productinformationapi-0.1.0/src/productinformationapi/__init__.py

@@ -0,0 +1,5 @@
+"""Small, dependency-free client for Product Information API."""
+
+from .client import APIError, ProductInformationAPI
+
+__all__ = ["APIError", "ProductInformationAPI"]

productinformationapi-0.1.0/src/productinformationapi/client.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import json
+import math
+import os
+import re
+from typing import Any
+from urllib.error import HTTPError
+from urllib.parse import urlsplit
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+DEFAULT_BASE_URL = "https://api.productinformationapi.com"
+
+
+class APIError(Exception):
+    """HTTP failure with the server's error code, request ID, and retry advice."""
+
+    def __init__(self, status: int, body: Any, headers: Any, *, invalid_response: bool = False):
+        error = body.get("error") if isinstance(body, dict) else None
+        error = error if isinstance(error, dict) else {}
+        message = error.get("message")
+        if not isinstance(message, str):
+            message = f"API returned HTTP {status}"
+            if invalid_response:
+                message += " with an invalid JSON response"
+        super().__init__(message)
+        self.status = status
+        self.code = error.get("code", "invalid_response" if invalid_response else "http_error")
+        self.request_id = error.get("requestId") or headers.get("X-Request-ID")
+        self.retryable = error.get("retryable") is True
+        retry_after = error.get("retryAfterS", headers.get("Retry-After"))
+        self.retry_after_s = (
+            int(retry_after) if re.fullmatch(r"[0-9]+", str(retry_after)) else None
+        )
+        self.body = body
+
+
+class _NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+def _required_string(value: Any, name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{name} must be a non-empty string")
+    return value.strip()
+
+
+def _timeout(value: float) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or value <= 0:
+        raise ValueError("timeout must be a positive number of seconds")
+    return value
+
+
+def _product_body(product_url: str, source_site: str | None = None) -> dict[str, Any]:
+    body = {"productUrl": _required_string(product_url, "product_url")}
+    if source_site is not None:
+        body["sourceSite"] = _required_string(source_site, "source_site")
+    return body
+
+
+def _bulk_body(items: list[str | dict[str, str]]) -> dict[str, Any]:
+    if not isinstance(items, list) or not items:
+        raise ValueError("items must be a non-empty list of URLs or productUrl/sourceSite dictionaries")
+    result = []
+    for item in items:
+        if isinstance(item, str):
+            result.append(_product_body(item))
+        elif isinstance(item, dict) and not item.keys() - {"productUrl", "sourceSite"}:
+            result.append(_product_body(item.get("productUrl"), item.get("sourceSite")))
+        else:
+            raise ValueError("each bulk item must be a URL or productUrl/sourceSite dictionary")
+    return {"items": result}
+
+
+class ProductInformationAPI:
+    """Synchronous client. Uses tenant API keys and never automatically retries requests."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 120,
+    ):
+        self._api_key = _required_string(
+            os.environ.get("PRODUCTINFORMATIONAPI_API_KEY") if api_key is None else api_key,
+            "api_key",
+        )
+        if not re.fullmatch(r"[!-~]+", self._api_key):
+            raise ValueError("api_key must contain visible ASCII only")
+        url = urlsplit(base_url)
+        local = url.hostname in {"localhost", "127.0.0.1", "::1"}
+        if (
+            not url.hostname
+            or (url.scheme != "https" and not (url.scheme == "http" and local))
+            or url.username is not None
+            or url.password is not None
+            or url.query
+            or url.fragment
+        ):
+            raise ValueError("base_url must use HTTPS (HTTP is allowed on localhost) without credentials, query, or fragment")
+        self._base_url = base_url.rstrip("/")
+        self._timeout = _timeout(timeout)
+        self._opener = build_opener(_NoRedirect())
+
+    def get_product_information(
+        self,
+        product_url: str,
+        *,
+        source_site: str | None = None,
+        include_gpsr: bool | None = None,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        body = _product_body(product_url, source_site)
+        if include_gpsr is not None:
+            if not isinstance(include_gpsr, bool):
+                raise ValueError("include_gpsr must be a boolean")
+            body["includeGpsr"] = include_gpsr
+        return self._post("/v1/product-information", body, idempotency_key, timeout)
+
+    def check_stock(
+        self,
+        product_url: str,
+        *,
+        source_site: str | None = None,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+        request_timeout_ms: int | None = None,
+    ) -> dict[str, Any]:
+        headers = {}
+        if request_timeout_ms is not None:
+            if isinstance(request_timeout_ms, bool) or not isinstance(request_timeout_ms, int) or not 1000 <= request_timeout_ms <= 100_000:
+                raise ValueError("request_timeout_ms must be an integer between 1000 and 100000")
+            if request_timeout_ms >= _timeout(self._timeout if timeout is None else timeout) * 1000:
+                raise ValueError("timeout must exceed request_timeout_ms / 1000; allow extra time for server cleanup")
+            headers["X-Request-Timeout-Ms"] = str(request_timeout_ms)
+        return self._post("/v1/product-stock", _product_body(product_url, source_site), idempotency_key, timeout, headers)
+
+    def get_product_information_bulk(
+        self,
+        items: list[str | dict[str, str]],
+        *,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        return self._post("/v1/product-information/bulk", _bulk_body(items), idempotency_key, timeout)
+
+    def check_stock_bulk(
+        self,
+        items: list[str | dict[str, str]],
+        *,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        return self._post("/v1/product-stock/bulk", _bulk_body(items), idempotency_key, timeout)
+
+    def _post(self, path, body, idempotency_key, timeout, extra_headers=None) -> dict[str, Any]:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "User-Agent": "ProductInformationAPI-Python/0.1.0",
+            **(extra_headers or {}),
+        }
+        if idempotency_key is not None:
+            if not isinstance(idempotency_key, str) or not re.fullmatch(r"[!-~]{1,255}", idempotency_key):
+                raise ValueError("idempotency_key must be 1-255 visible ASCII characters")
+            headers["Idempotency-Key"] = idempotency_key
+        request = Request(
+            f"{self._base_url}{path}",
+            data=json.dumps(body).encode("utf-8"),
+            headers=headers,
+            method="POST",
+        )
+        try:
+            response = self._opener.open(request, timeout=_timeout(self._timeout if timeout is None else timeout))
+        except HTTPError as exc:
+            response = exc
+        with response:
+            raw = response.read()
+            try:
+                result = json.loads(raw)
+            except (ValueError, UnicodeDecodeError):
+                result = None
+            if not 200 <= response.status < 300:
+                raise APIError(response.status, result, response.headers)
+            if not isinstance(result, dict):
+                raise APIError(response.status, result, response.headers, invalid_response=True)
+            return result

productinformationapi-0.1.0/src/productinformationapi.egg-info/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: productinformationapi
+Version: 0.1.0
+Summary: Product information and stock checks with Product Information API
+Author-email: HustleGotReal <contact@hustlegotreal.com>
+License-Expression: MIT
+Project-URL: Homepage, https://productinformationapi.com
+Keywords: product-information,stock,scraping,api,sdk
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Product Information API for Python
+
+Product information and stock checks in Python 3.11+, with type hints and no runtime dependencies.
+
+## Install
+
+```sh
+python -m pip install productinformationapi
+```
+
+Or install the distributed wheel with `python -m pip install ./productinformationapi-0.1.0-py3-none-any.whl`.
+
+## Quick start
+
+Use a tenant API key from your Product Information API account. MCP OAuth access tokens are scoped
+to MCP and cannot authenticate these REST requests. Keep the key in your server environment:
+
+```sh
+export PRODUCTINFORMATIONAPI_API_KEY='your-api-key'
+```
+
+```python
+from productinformationapi import ProductInformationAPI
+
+client = ProductInformationAPI()  # Reads PRODUCTINFORMATIONAPI_API_KEY.
+url = "https://www.amazon.com/dp/B0D3BCR3V7"
+
+product = client.get_product_information(url)
+print((product.get("productInformation") or {}).get("title"), product["creditsCharged"])
+
+stock = client.check_stock(url)
+print(stock["inStock"], stock["offers"], stock["creditsRemaining"])
+```
+
+Methods return the complete API response as a dictionary. Response keys retain the API's camelCase
+names. The client is synchronous; in an asyncio application, use a worker thread:
+
+```python
+import asyncio
+
+stock = await asyncio.to_thread(client.check_stock, url)
+```
+
+Cancelling the asyncio waiter does not cancel the worker thread's HTTP request; its socket timeout
+still applies.
+
+## Bulk
+
+```python
+batch = client.check_stock_bulk([
+    "https://www.amazon.com/dp/B0D3BCR3V7",
+    {"productUrl": "https://www.amazon.co.uk/dp/B0D3BCR3V7", "sourceSite": "amazon_gb"},
+])
+
+for row in batch["results"]:
+    if row["httpStatus"] == 200:
+        print(row["index"], row["result"])
+    else:
+        print(row["index"], row["httpStatus"], row["result"]["error"])
+
+# Product information uses the same inputs:
+products = client.get_product_information_bulk([
+    "https://www.amazon.com/dp/B0D3BCR3V7",
+])
+```
+
+Bulk calls return inline. A successful HTTP response can contain failed items; inspect each
+`httpStatus`. The current default server limit is 100 items per batch. Items are never silently
+split, retried, or reordered. Large batches may require a longer HTTP timeout.
+
+## Options and errors
+
+```python
+from uuid import uuid4
+from productinformationapi import APIError
+
+request_key = str(uuid4())  # Retain this key if you retry this exact request.
+try:
+    stock = client.check_stock(
+        url,
+        idempotency_key=request_key,
+        timeout=120,
+        request_timeout_ms=30_000,
+    )
+    print(stock["inStock"])
+except APIError as error:
+    print(error.status, error.code, error.request_id, error.retry_after_s)
+```
+
+- Constructor: `ProductInformationAPI(api_key=None, *, base_url="https://api.productinformationapi.com", timeout=120)`.
+- All methods accept `idempotency_key` and `timeout` in seconds. `timeout` is the standard-library
+  socket timeout for blocking operations, not a guaranteed total wall-clock deadline.
+- Singular methods accept `source_site`. `get_product_information` also accepts
+  `include_gpsr=True` for Amazon DE GPSR details. Bulk requests do not accept GPSR options.
+- `request_timeout_ms` applies only to singular stock requests, from 1000 to 100000 milliseconds.
+  It shortens the server execution budget. Leave additional time in `timeout` for server cleanup.
+- Timeouts do not prove the server did no work or charged no credits. There are no automatic
+  retries. Reuse an idempotency key only for the same operation and payload; keep bulk items in
+  the same order on a retry. Keys must contain 1–255 visible ASCII characters.
+- `APIError` exposes `status`, `code`, `request_id`, `retryable`, `retry_after_s`, and the parsed
+  response as `body`. HTML edge failures still produce `APIError`. Bulk item errors remain in
+  `batch["results"]`. Transport failures retain standard-library exceptions such as `URLError`
+  and `TimeoutError`.
+
+## Webhooks
+
+Scrape-result webhooks and asynchronous jobs are not currently implemented by the API. These
+methods return the result directly; no webhook URL option is available.
+
+## Support and license
+
+Visit [Product Information API](https://productinformationapi.com) or contact
+[contact@hustlegotreal.com](mailto:contact@hustlegotreal.com).
+
+This SDK is MIT licensed. API access requires a separate account and is subject to the service's
+terms and credit usage.

productinformationapi-0.1.0/src/productinformationapi.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/productinformationapi/__init__.py
+src/productinformationapi/client.py
+src/productinformationapi/py.typed
+src/productinformationapi.egg-info/PKG-INFO
+src/productinformationapi.egg-info/SOURCES.txt
+src/productinformationapi.egg-info/dependency_links.txt
+src/productinformationapi.egg-info/top_level.txt
+tests/test_client.py

productinformationapi-0.1.0/src/productinformationapi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

productinformationapi-0.1.0/src/productinformationapi.egg-info/top_level.txt

@@ -0,0 +1 @@
+productinformationapi

productinformationapi-0.1.0/tests/test_client.py

@@ -0,0 +1,177 @@
+import json
+import os
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from unittest.mock import patch
+
+from productinformationapi import APIError, ProductInformationAPI
+
+URL = "https://www.amazon.com/dp/B0D3BCR3V7"
+STOCK = {"outcome": "OK", "inStock": True, "offers": [], "creditsCharged": 1, "creditsRemaining": 9}
+
+
+class ClientTests(unittest.TestCase):
+    def setUp(self):
+        self.requests = []
+        self.status = 200
+        self.body = json.dumps(STOCK).encode()
+        self.headers = {}
+        self.stall_body = False
+        self.stop = threading.Event()
+        owner = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def do_POST(self):
+                owner.requests.append({
+                    "path": self.path,
+                    "headers": self.headers,
+                    "body": json.loads(self.rfile.read(int(self.headers["Content-Length"]))),
+                })
+                self.send_response(owner.status)
+                for name, value in owner.headers.items():
+                    self.send_header(name, value)
+                self.end_headers()
+                if owner.stall_body:
+                    self.wfile.write(b'{"outcome":')
+                    self.wfile.flush()
+                    owner.stop.wait(5)
+                else:
+                    self.wfile.write(owner.body)
+
+            def log_message(self, *_args):
+                pass
+
+        self.server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        self.thread = threading.Thread(target=self.server.serve_forever, kwargs={"poll_interval": 0.01})
+        self.thread.start()
+        self.base_url = f"http://127.0.0.1:{self.server.server_port}"
+        self.client = ProductInformationAPI("test-key", base_url=self.base_url + "/")
+
+    def tearDown(self):
+        self.stop.set()
+        self.server.shutdown()
+        self.server.server_close()
+        self.thread.join()
+
+    def test_all_four_operations_match_public_contract(self):
+        result = self.client.get_product_information(URL, source_site="amazon_us", include_gpsr=False, idempotency_key="info-1")
+        self.assertEqual(result, STOCK)
+        self.client.check_stock(URL, request_timeout_ms=30_000, idempotency_key="stock-1")
+        self.client.get_product_information_bulk([URL, {"productUrl": URL, "sourceSite": "amazon_us"}], idempotency_key="batch-1")
+        self.client.check_stock_bulk([URL])
+        self.assertEqual([r["path"] for r in self.requests], [
+            "/v1/product-information", "/v1/product-stock", "/v1/product-information/bulk", "/v1/product-stock/bulk",
+        ])
+        self.assertEqual([r["body"] for r in self.requests], [
+            {"productUrl": URL, "sourceSite": "amazon_us", "includeGpsr": False},
+            {"productUrl": URL},
+            {"items": [{"productUrl": URL}, {"productUrl": URL, "sourceSite": "amazon_us"}]},
+            {"items": [{"productUrl": URL}]},
+        ])
+        for request in self.requests:
+            self.assertEqual(request["headers"]["Authorization"], "Bearer test-key")
+            self.assertEqual(request["headers"]["Content-Type"], "application/json")
+            self.assertTrue(request["headers"]["User-Agent"].startswith("ProductInformationAPI-Python/"))
+        self.assertEqual(self.requests[0]["headers"]["Idempotency-Key"], "info-1")
+        self.assertEqual(self.requests[1]["headers"]["X-Request-Timeout-Ms"], "30000")
+        self.assertEqual(self.requests[2]["headers"]["Idempotency-Key"], "batch-1")
+        self.assertIsNone(self.requests[3]["headers"]["Idempotency-Key"])
+
+    def test_bulk_preserves_partial_errors_and_order(self):
+        batch = {
+            "requestId": "req_bulk", "total": 2, "succeeded": 1, "failed": 1, "retryable": 1,
+            "results": [
+                {"index": 0, "httpStatus": 200, "result": STOCK},
+                {"index": 1, "httpStatus": 503, "result": {"error": {"code": "scrape_unavailable", "retryable": True}}},
+            ],
+        }
+        self.body = json.dumps(batch).encode()
+        self.assertEqual(self.client.check_stock_bulk([URL, URL]), batch)
+
+    def test_api_errors_preserve_metadata_without_retrying(self):
+        for index, status in enumerate((401, 402, 409, 429, 503), 1):
+            with self.subTest(status=status):
+                body = {"error": {"code": "example_error", "message": "Request unavailable", "requestId": "req_123", "retryable": status >= 429, "retryAfterS": 7}}
+                self.status = status
+                self.body = json.dumps(body).encode()
+                self.headers = {"Retry-After": "9"}
+                with self.assertRaises(APIError) as caught:
+                    self.client.check_stock(URL)
+                error = caught.exception
+                self.assertEqual(error.status, status)
+                self.assertEqual(error.code, "example_error")
+                self.assertEqual(error.request_id, "req_123")
+                self.assertEqual(error.retry_after_s, 7)
+                self.assertEqual(error.retryable, status >= 429)
+                self.assertEqual(error.body, body)
+                self.assertEqual(len(self.requests), index)
+
+    def test_html_edge_error_preserves_headers(self):
+        self.status = 403
+        self.body = b"<html>Forbidden</html>"
+        self.headers = {"X-Request-ID": "edge_1", "Retry-After": "2"}
+        with self.assertRaises(APIError) as caught:
+            self.client.check_stock(URL)
+        self.assertEqual(caught.exception.status, 403)
+        self.assertEqual(caught.exception.request_id, "edge_1")
+        self.assertEqual(caught.exception.retry_after_s, 2)
+        self.assertIsNone(caught.exception.body)
+
+    def test_malformed_success(self):
+        for body in (b"not json", b"[]", b"null"):
+            self.body = body
+            with self.assertRaises(APIError) as caught:
+                self.client.check_stock(URL)
+            self.assertEqual(caught.exception.code, "invalid_response")
+            self.assertEqual(caught.exception.status, 200)
+
+    def test_does_not_follow_redirects(self):
+        for status in (301, 302, 303, 307, 308):
+            self.status = status
+            self.headers = {"Location": self.base_url + "/redirect-target"}
+            with self.assertRaises(APIError) as caught:
+                self.client.check_stock(URL)
+            self.assertEqual(caught.exception.status, status)
+        self.assertEqual(len(self.requests), 5)
+        self.assertTrue(all(r["path"] == "/v1/product-stock" for r in self.requests))
+
+    def test_timeout_covers_stalled_response_body(self):
+        self.stall_body = True
+        with self.assertRaises(TimeoutError):
+            self.client.check_stock(URL, timeout=0.1)
+        self.assertEqual(len(self.requests), 1)
+
+    def test_invalid_inputs_are_rejected_before_sending(self):
+        for operation in (
+            lambda: self.client.check_stock(""),
+            lambda: self.client.check_stock_bulk([]),
+            lambda: self.client.check_stock_bulk([{"productUrl": URL, "includeGpsr": True}]),
+            lambda: self.client.get_product_information(URL, include_gpsr="true"),
+            lambda: self.client.check_stock(URL, request_timeout_ms=100),
+            lambda: self.client.check_stock(URL, request_timeout_ms=5000, timeout=5),
+            lambda: self.client.check_stock(URL, timeout=0),
+            lambda: self.client.check_stock(URL, timeout=float("nan")),
+        ):
+            with self.assertRaises(ValueError):
+                operation()
+        for key in ("", "has spaces", "x" * 256, "new\nline"):
+            with self.assertRaises(ValueError):
+                self.client.check_stock(URL, idempotency_key=key)
+        self.assertEqual(self.requests, [])
+
+    def test_credential_and_transport_configuration(self):
+        for base_url in ("http://example.com", "ftp://example.com", "https://user:pass@example.com", "https://example.com?key=x", "https://example.com#x"):
+            with self.assertRaises(ValueError):
+                ProductInformationAPI("test-key", base_url=base_url)
+        for api_key in ("", "key\nInjected"):
+            with self.assertRaises(ValueError):
+                ProductInformationAPI(api_key)
+        self.assertNotIn("test-key", repr(self.client))
+        with patch.dict(os.environ, {"PRODUCTINFORMATIONAPI_API_KEY": "environment-key"}):
+            ProductInformationAPI(base_url=self.base_url).check_stock(URL)
+        self.assertEqual(self.requests[-1]["headers"]["Authorization"], "Bearer environment-key")
+
+
+if __name__ == "__main__":
+    unittest.main()