onhand-mcp 0.1.0a1__tar.gz

onhand_mcp-0.1.0a1/.gitignore

@@ -0,0 +1,20 @@
+node_modules
+.pnpm-store
+dist
+.next
+.turbo
+.DS_Store
+*.log
+coverage
+.stripe-test-clocks
+.env
+.env.*
+!.env.example
+*.tsbuildinfo
+
+# regenerated by `next dev`; apps/web/AGENTS.md is the tracked original
+apps/web/CLAUDE.md
+
+# macOS/iCloud duplicate artifacts ("context 2.ts", "Dockerfile 2")
+* [0-9]
+* [0-9].*

onhand_mcp-0.1.0a1/LICENSE

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

onhand_mcp-0.1.0a1/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.5
+Name: onhand-mcp
+Version: 0.1.0a1
+Summary: Python client for the Onhand public API
+Project-URL: Homepage, https://askonhand.com/use
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Onhand Python SDK
+
+Thin, typed access to the versioned Onhand public API with no runtime
+dependencies.
+
+```bash
+pip install onhand-mcp
+```
+
+```python
+from onhand import OnhandClient
+
+onhand = OnhandClient("https://mcp.askonhand.com")
+result = onhand.search_offerings(
+    {"lat": 41.88, "lng": -87.63, "q": "running shoes", "surface": "chatgpt"}
+)
+```
+
+Pass `token_provider` for authenticated methods. The callback is evaluated for
+each request, and the SDK never persists the token.

onhand_mcp-0.1.0a1/README.md

@@ -0,0 +1,20 @@
+# Onhand Python SDK
+
+Thin, typed access to the versioned Onhand public API with no runtime
+dependencies.
+
+```bash
+pip install onhand-mcp
+```
+
+```python
+from onhand import OnhandClient
+
+onhand = OnhandClient("https://mcp.askonhand.com")
+result = onhand.search_offerings(
+    {"lat": 41.88, "lng": -87.63, "q": "running shoes", "surface": "chatgpt"}
+)
+```
+
+Pass `token_provider` for authenticated methods. The callback is evaluated for
+each request, and the SDK never persists the token.

onhand_mcp-0.1.0a1/onhand/__init__.py

@@ -0,0 +1,18 @@
+from ._generated import (
+    SearchOffering,
+    SearchOfferingsInput,
+    SearchOfferingsResponse,
+    SearchWebsiteItem,
+    WebsiteItemBand,
+)
+from .client import OnhandApiError, OnhandClient
+
+__all__ = [
+    "OnhandApiError",
+    "OnhandClient",
+    "SearchOffering",
+    "SearchOfferingsInput",
+    "SearchOfferingsResponse",
+    "SearchWebsiteItem",
+    "WebsiteItemBand",
+]

onhand_mcp-0.1.0a1/onhand/_generated.py

@@ -0,0 +1,93 @@
+# Generated from the Onhand OpenAPI contract. Do not edit.
+from collections.abc import Callable
+from typing import Literal, TypedDict, cast
+
+Surface = Literal["onhand", "claude", "chatgpt", "grok", "cursor", "muse", "gemini"]
+OfferingKind = Literal["item", "service"]
+TrustTier = Literal[1, 2, 3]
+Freshness = Literal["fresh", "aging", "stale"]
+SourceType = Literal["register", "merchant_upload", "website_prefill"]
+Availability = Literal["in_stock", "low", "out", "bookable", "unavailable", "unknown"] | None
+WebsiteItemBand = Literal["listed_on_website", "possibly_offered"]
+
+
+class _SearchOfferingsInputRequired(TypedDict):
+    lat: float
+    lng: float
+    q: str
+
+
+class SearchOfferingsInput(_SearchOfferingsInputRequired, total=False):
+    radius_m: int
+    surface: Surface
+    attributes: dict[str, str]
+
+
+class SearchOfferingImage(TypedDict):
+    url: str
+    alt: str | None
+
+
+class SearchOffering(TypedDict):
+    offering_id: str
+    title: str
+    business_id: str
+    display_name: str
+    price_cents: int
+    kind: OfferingKind
+    distance_meters: float
+    trust_tier: TrustTier
+    freshness: Freshness
+    data_age_seconds: int
+    source_type: SourceType
+    availability: Availability
+    section: str | None
+    description: str | None
+    duration_minutes: int | None
+    last_confirmed_at: str | None
+    attributes: dict[str, str]
+    images: list[SearchOfferingImage]
+
+
+class SearchWebsiteItem(TypedDict):
+    business_id: str
+    display_name: str
+    title: str
+    kind: Literal["item", "service"]
+    section: str | None
+    distance_meters: float
+    source_type: Literal["public_website"]
+    band: WebsiteItemBand
+    label: str
+    source_url: str
+    last_seen_at: str
+
+
+class SearchOfferingsResponse(TypedDict):
+    data: list[SearchOffering]
+    website_items: list[SearchWebsiteItem]
+
+
+class ErrorDetail(TypedDict):
+    code: str
+    message: str
+
+
+class ErrorResponse(TypedDict):
+    error: ErrorDetail
+
+
+GeneratedRequester = Callable[[str, str, object], object]
+
+
+class GeneratedOnhandApi:
+    def __init__(self, request: GeneratedRequester) -> None:
+        self._request = request
+
+    def search_offerings(
+        self, input: SearchOfferingsInput
+    ) -> SearchOfferingsResponse:
+        return cast(
+            SearchOfferingsResponse,
+            self._request("POST", "/v1/offerings/search", input),
+        )

onhand_mcp-0.1.0a1/onhand/client.py

@@ -0,0 +1,98 @@
+import json
+import time
+from collections.abc import Callable
+from typing import cast
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from ._generated import GeneratedOnhandApi, SearchOfferingsInput, SearchOfferingsResponse
+
+SDK_VERSION = "0.1.0a1"
+TokenProvider = Callable[[], str | None]
+
+
+class OnhandApiError(Exception):
+    def __init__(
+        self, code: str, message: str, status: int, request_id: str | None = None
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.request_id = request_id
+
+
+class OnhandClient:
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        token_provider: TokenProvider | None = None,
+        timeout: float = 10.0,
+        max_retries: int = 2,
+        retry_delay: float = 0.1,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token_provider = token_provider
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._retry_delay = retry_delay
+        self._api = GeneratedOnhandApi(self._request)
+
+    def search_offerings(
+        self, input: SearchOfferingsInput
+    ) -> SearchOfferingsResponse:
+        return self._api.search_offerings(input)
+
+    def _request(self, method: str, path: str, body: object) -> object:
+        for attempt in range(self._max_retries + 1):
+            token = self._token_provider() if self._token_provider else None
+            headers = {
+                "Content-Type": "application/json",
+                "X-Onhand-Client-Version": SDK_VERSION,
+            }
+            if token:
+                headers["Authorization"] = f"Bearer {token}"
+            request = Request(
+                f"{self._base_url}{path}",
+                data=json.dumps(body).encode(),
+                headers=headers,
+                method=method,
+            )
+            try:
+                with urlopen(request, timeout=self._timeout) as response:
+                    return cast(object, json.loads(response.read()))
+            except HTTPError as error:
+                if attempt < self._max_retries and _retryable(error.code):
+                    self._delay(attempt)
+                    continue
+                payload = _error_payload(error.read())
+                raise OnhandApiError(
+                    payload.get("code", "http_error"),
+                    payload.get("message", f"Onhand request failed ({error.code})."),
+                    error.code,
+                    error.headers.get("X-Request-Id") if error.headers else None,
+                ) from error
+            except (TimeoutError, URLError) as error:
+                if attempt < self._max_retries:
+                    self._delay(attempt)
+                    continue
+                raise OnhandApiError(
+                    "transport_error", "Onhand request failed.", 0
+                ) from error
+        raise OnhandApiError("transport_error", "Onhand request failed.", 0)
+
+    def _delay(self, attempt: int) -> None:
+        time.sleep(self._retry_delay * (2**attempt))
+
+
+def _retryable(status: int) -> bool:
+    return status == 429 or status >= 500
+
+
+def _error_payload(raw: bytes) -> dict[str, str]:
+    try:
+        payload = json.loads(raw)
+        error = payload.get("error", {}) if isinstance(payload, dict) else {}
+        return error if isinstance(error, dict) else {}
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return {}

onhand_mcp-0.1.0a1/onhand/py.typed

@@ -0,0 +1 @@
+

onhand_mcp-0.1.0a1/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "onhand-mcp"
+version = "0.1.0a1"
+description = "Python client for the Onhand public API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = []
+
+[project.urls]
+Homepage = "https://askonhand.com/use"
+
+[tool.hatch.build.targets.wheel]
+packages = ["onhand"]

onhand_mcp-0.1.0a1/tests/test_client.py

@@ -0,0 +1,80 @@
+import json
+import sys
+import unittest
+from io import BytesIO
+from pathlib import Path
+from unittest.mock import patch
+from urllib.error import HTTPError, URLError
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from onhand import OnhandApiError, OnhandClient  # noqa: E402
+
+FIXTURE = json.loads(
+    (Path(__file__).resolve().parents[3] / "test/fixtures/public-api/search.json")
+    .read_text()
+)
+
+
+class FakeResponse:
+    def __init__(self, body: object) -> None:
+        self._body = json.dumps(body).encode()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_args):
+        return None
+
+    def read(self) -> bytes:
+        return self._body
+
+
+class OnhandClientTest(unittest.TestCase):
+    @patch("onhand.client.urlopen")
+    def test_generated_route_auth_and_metadata(self, open_url):
+        open_url.return_value = FakeResponse(FIXTURE["response"])
+        client = OnhandClient(
+            "https://api.example/", token_provider=lambda: "secret-token"
+        )
+
+        self.assertEqual(client.search_offerings(FIXTURE["request"]), FIXTURE["response"])
+        request = open_url.call_args.args[0]
+        headers = {key.lower(): value for key, value in request.header_items()}
+        self.assertEqual(request.full_url, "https://api.example/v1/offerings/search")
+        self.assertEqual(headers["authorization"], "Bearer secret-token")
+        self.assertEqual(headers["x-onhand-client-version"], "0.1.0a1")
+
+    @patch("onhand.client.urlopen")
+    def test_typed_api_error(self, open_url):
+        open_url.side_effect = HTTPError(
+            "https://api.example",
+            400,
+            "Bad request",
+            {"X-Request-Id": "req-error"},
+            BytesIO(
+                json.dumps(
+                    {"error": {"code": "invalid_request", "message": "Bad request."}}
+                ).encode()
+            ),
+        )
+        client = OnhandClient("https://api.example", max_retries=0)
+
+        with self.assertRaises(OnhandApiError) as raised:
+            client.search_offerings(FIXTURE["request"])
+        self.assertEqual(raised.exception.code, "invalid_request")
+        self.assertEqual(raised.exception.status, 400)
+        self.assertEqual(raised.exception.request_id, "req-error")
+
+    @patch("onhand.client.time.sleep")
+    @patch("onhand.client.urlopen")
+    def test_retries_transient_transport_failures(self, open_url, _sleep):
+        open_url.side_effect = [URLError("offline"), FakeResponse(FIXTURE["response"])]
+        client = OnhandClient("https://api.example", max_retries=1)
+
+        self.assertEqual(client.search_offerings(FIXTURE["request"]), FIXTURE["response"])
+        self.assertEqual(open_url.call_count, 2)
+
+
+if __name__ == "__main__":
+    unittest.main()