healchain-sdk 0.1.0__tar.gz

healchain_sdk-0.1.0/LICENSE (1)

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

healchain_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: healchain-sdk
+Version: 0.1.0
+Summary: Python SDK for HealChain — self-healing decentralized storage via Reed-Solomon erasure coding
+Author-email: HealChain Team <info@healchain.org>
+License: MIT
+Project-URL: Homepage, https://healchain.org
+Project-URL: Repository, https://github.com/karmaxul/ci-quantum-storage
+Project-URL: Bug Tracker, https://github.com/karmaxul/ci-quantum-storage/issues
+Keywords: healchain,blockchain,storage,reed-solomon,erasure-coding,ethereum,arbitrum,decentralized
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE (1)
+License-File: LICENSE (1):Zone.Identifier
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Dynamic: license-file

healchain_sdk-0.1.0/healchain/__init__.py

@@ -0,0 +1,18 @@
+"""
+HealChain Python SDK
+Self-healing decentralized storage via Reed-Solomon erasure coding.
+
+Quick start::
+
+    from healchain import HealChain
+
+    hc = HealChain(api_url="https://api.healchain.org")
+    result = hc.store("Hello World", label="my record")
+    record = hc.retrieve(result["record_id"])
+    print(record["text"])  # Hello World
+"""
+
+from .client import HealChain, HealChainError
+
+__all__ = ["HealChain", "HealChainError"]
+__version__ = "0.1.0"

healchain_sdk-0.1.0/healchain/client.py

@@ -0,0 +1,354 @@
+"""
+HealChain Python SDK v0.1.0
+REST API client for HealChain — self-healing decentralized storage.
+
+Works with Python 3.8+ using only the standard library (urllib).
+Optional: install `requests` for a more ergonomic HTTP experience.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.request
+import urllib.error
+import urllib.parse
+from typing import Any, Callable, Optional, Union
+
+
+# ── Constants ─────────────────────────────────────────────────────────────────
+
+DEFAULT_API_URL       = "https://api.healchain.org"
+DEFAULT_POLL_INTERVAL = 4.0    # seconds between fulfillment polls
+DEFAULT_POLL_TIMEOUT  = 120.0  # seconds before giving up
+DEFAULT_DATA_SHARDS   = 10
+DEFAULT_PARITY_SHARDS = 4
+
+
+# ── Exceptions ────────────────────────────────────────────────────────────────
+
+class HealChainError(Exception):
+    """Raised on any HealChain API or network error."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: Optional[int] = None,
+        code: Optional[str] = None,
+        response: Any = None,
+    ):
+        super().__init__(message)
+        self.status   = status
+        self.code     = code
+        self.response = response
+
+    def __repr__(self) -> str:
+        return (
+            f"HealChainError({str(self)!r}, "
+            f"status={self.status}, code={self.code!r})"
+        )
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _to_hex(data: Union[str, bytes, bytearray]) -> str:
+    """Convert string or bytes to 0x-prefixed hex."""
+    if isinstance(data, str):
+        if data.startswith("0x"):
+            return data
+        return "0x" + data.encode("utf-8").hex()
+    if isinstance(data, (bytes, bytearray)):
+        return "0x" + data.hex()
+    raise HealChainError(
+        f"store() data must be str or bytes, got {type(data).__name__}"
+    )
+
+
+# ── Main client ───────────────────────────────────────────────────────────────
+
+class HealChain:
+    """
+    HealChain API client.
+
+    Example::
+
+        from healchain import HealChain
+
+        hc = HealChain(api_url="https://api.healchain.org")
+
+        # Store data
+        result = hc.store("Hello World", label="my record")
+        print(f"Stored as record #{result['record_id']} on chain {result['chain_id']}")
+
+        # Retrieve — auto-discovers chain from GlobalRegistry
+        record = hc.retrieve(result["record_id"])
+        print(record["text"])
+    """
+
+    def __init__(
+        self,
+        api_url: str = DEFAULT_API_URL,
+        *,
+        api_key: Optional[str] = None,
+        network: str = "sepolia",
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        poll_timeout: float = DEFAULT_POLL_TIMEOUT,
+        data_shards: int = DEFAULT_DATA_SHARDS,
+        parity_shards: int = DEFAULT_PARITY_SHARDS,
+        timeout: float = 30.0,
+    ):
+        """
+        Args:
+            api_url:       API base URL (default: https://api.healchain.org)
+            api_key:       Optional API key
+            network:       Default network: 'sepolia' or 'arbitrum'
+            poll_interval: Seconds between oracle fulfillment polls
+            poll_timeout:  Max seconds to wait for oracle fulfillment
+            data_shards:   Default RS data shards
+            parity_shards: Default RS parity shards
+            timeout:       HTTP request timeout in seconds
+        """
+        self.api_url       = api_url.rstrip("/")
+        self.api_key       = api_key
+        self.network       = network
+        self.poll_interval = poll_interval
+        self.poll_timeout  = poll_timeout
+        self.data_shards   = data_shards
+        self.parity_shards = parity_shards
+        self.timeout       = timeout
+
+    # ── Internal request ──────────────────────────────────────────────────────
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Optional[dict] = None,
+    ) -> Any:
+        url = f"{self.api_url}{path}"
+        data = json.dumps(body).encode() if body is not None else None
+
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": "healchain-sdk-python/0.1.0",
+        }
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                raw = resp.read()
+                return json.loads(raw) if raw else {}
+        except urllib.error.HTTPError as exc:
+            raw = exc.read()
+            try:
+                body_json = json.loads(raw)
+                msg = body_json.get("error", str(exc))
+            except Exception:
+                msg = raw.decode(errors="replace") or str(exc)
+            raise HealChainError(msg, status=exc.code, response=body_json if raw else None)
+        except urllib.error.URLError as exc:
+            raise HealChainError(
+                f"Network error: {exc.reason}", code="NETWORK_ERROR"
+            ) from exc
+
+    # ── health() ──────────────────────────────────────────────────────────────
+
+    def health(self) -> dict:
+        """
+        Check service health.
+
+        Returns:
+            dict with keys: status, version, geth, last_block
+        """
+        return self._request("GET", "/health")
+
+    # ── store() ───────────────────────────────────────────────────────────────
+
+    def store(
+        self,
+        data: Union[str, bytes, bytearray],
+        *,
+        label: str = "sdk upload",
+        network: Optional[str] = None,
+        data_shards: Optional[int] = None,
+        parity_shards: Optional[int] = None,
+        on_pending: Optional[Callable[[dict], None]] = None,
+        on_fulfilled: Optional[Callable[[dict], None]] = None,
+    ) -> dict:
+        """
+        Store data on-chain. Blocks until the oracle fulfills the request.
+
+        Args:
+            data:          Data to store (str or bytes)
+            label:         Record label (default: 'sdk upload')
+            network:       Override network: 'sepolia' or 'arbitrum'
+            data_shards:   Override RS data shards
+            parity_shards: Override RS parity shards
+            on_pending:    Called with {'request_id', 'tx'} when submitted
+            on_fulfilled:  Called with result dict when oracle fulfills
+
+        Returns:
+            dict with keys: record_id, request_id, tx, chain_id,
+                            original_size, encoded_size
+
+        Raises:
+            HealChainError: on network error or fulfillment timeout
+        """
+        hex_data = _to_hex(data)
+
+        payload = {
+            "data":         hex_data,
+            "label":        label,
+            "network":      network or self.network,
+            "dataShards":   data_shards  or self.data_shards,
+            "parityShards": parity_shards or self.parity_shards,
+        }
+
+        submitted = self._request("POST", "/storeOnChain", body=payload)
+
+        # Devnet returns synchronously
+        if submitted.get("status") == "success" and "recordId" in submitted:
+            return self._normalise_store(submitted)
+
+        # Testnet: poll for oracle fulfillment
+        request_id = submitted.get("requestId")
+        tx         = submitted.get("tx")
+        if not request_id:
+            raise HealChainError(
+                "No requestId returned from store", response=submitted
+            )
+
+        if on_pending:
+            on_pending({"request_id": str(request_id), "tx": tx})
+
+        return self._poll_fulfillment(request_id, tx, on_fulfilled)
+
+    def _poll_fulfillment(
+        self,
+        request_id: str,
+        tx: str,
+        on_fulfilled: Optional[Callable[[dict], None]],
+    ) -> dict:
+        deadline = time.monotonic() + self.poll_timeout
+
+        while time.monotonic() < deadline:
+            time.sleep(self.poll_interval)
+            try:
+                status = self._request(
+                    "GET",
+                    f"/sepoliaStatus?requestId={urllib.parse.quote(str(request_id))}",
+                )
+            except HealChainError:
+                continue  # transient error — keep polling
+
+            if status.get("status") == "fulfilled":
+                result = {
+                    "record_id":    str(status.get("recordId", request_id)),
+                    "request_id":   str(request_id),
+                    "tx":           tx,
+                    "chain_id":     status.get("chainId"),
+                    "original_size": status.get("originalSize"),
+                    "encoded_size":  status.get("encodedSize"),
+                    "total_records": status.get("totalRecords"),
+                }
+                if on_fulfilled:
+                    on_fulfilled(result)
+                return result
+
+        raise HealChainError(
+            f"Oracle fulfillment timed out after {self.poll_timeout}s "
+            f"(request_id={request_id})",
+            code="FULFILLMENT_TIMEOUT",
+        )
+
+    @staticmethod
+    def _normalise_store(resp: dict) -> dict:
+        return {
+            "record_id":    str(resp.get("recordId", "")),
+            "request_id":   resp.get("requestId"),
+            "tx":           resp.get("tx"),
+            "chain_id":     resp.get("chainId"),
+            "original_size": resp.get("originalSize"),
+            "encoded_size":  resp.get("encodedSize"),
+        }
+
+    # ── retrieve() ────────────────────────────────────────────────────────────
+
+    def retrieve(self, record_id: Union[str, int]) -> dict:
+        """
+        Retrieve a record by ID. Automatically routes to the correct chain
+        via the GlobalRegistry.
+
+        Args:
+            record_id: Record ID (str or int)
+
+        Returns:
+            dict with keys: record_id, data (hex), text, bytes, chain_id
+
+        Raises:
+            HealChainError: if record not found or network error
+        """
+        path   = f"/retrieve?id={urllib.parse.quote(str(record_id))}"
+        result = self._request("GET", path)
+        return {
+            "record_id": str(result.get("recordId", record_id)),
+            "data":      result.get("data"),
+            "text":      result.get("text"),
+            "bytes":     result.get("bytes"),
+            "chain_id":  result.get("chainId"),
+        }
+
+    # ── get_metadata() ────────────────────────────────────────────────────────
+
+    def get_metadata(self, record_id: Union[str, int]) -> dict:
+        """
+        Get record metadata without fetching the full data payload.
+
+        Args:
+            record_id: Record ID (str or int)
+
+        Returns:
+            dict with label, owner, original_size, encoded_size,
+                  data_shards, parity_shards, timestamp, data_hash
+        """
+        path   = f"/getMetadata?id={urllib.parse.quote(str(record_id))}"
+        result = self._request("GET", path)
+        return {
+            "record_id":    str(result.get("recordId", record_id)),
+            "label":        result.get("label"),
+            "owner":        result.get("owner"),
+            "original_size": result.get("originalSize"),
+            "encoded_size":  result.get("encodedSize"),
+            "data_shards":   result.get("dataShards"),
+            "parity_shards": result.get("parityShards"),
+            "timestamp":     result.get("timestamp"),
+            "data_hash":     result.get("dataHash"),
+        }
+
+    # ── list() ────────────────────────────────────────────────────────────────
+
+    def list(self, page: int = 0, limit: int = 10) -> dict:
+        """
+        List records with pagination.
+
+        Args:
+            page:  Page number, 0-indexed (default: 0)
+            limit: Records per page, max 50 (default: 10)
+
+        Returns:
+            dict with keys: records, total, pages, page, limit
+        """
+        path   = f"/listRecords?page={page}&limit={limit}"
+        result = self._request("GET", path)
+        return {
+            "records": result.get("records", []),
+            "total":   result.get("total", 0),
+            "pages":   result.get("pages", 1),
+            "page":    result.get("page", page),
+            "limit":   result.get("limit", limit),
+        }

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

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: healchain-sdk
+Version: 0.1.0
+Summary: Python SDK for HealChain — self-healing decentralized storage via Reed-Solomon erasure coding
+Author-email: HealChain Team <info@healchain.org>
+License: MIT
+Project-URL: Homepage, https://healchain.org
+Project-URL: Repository, https://github.com/karmaxul/ci-quantum-storage
+Project-URL: Bug Tracker, https://github.com/karmaxul/ci-quantum-storage/issues
+Keywords: healchain,blockchain,storage,reed-solomon,erasure-coding,ethereum,arbitrum,decentralized
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE (1)
+License-File: LICENSE (1):Zone.Identifier
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Dynamic: license-file

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

@@ -0,0 +1,11 @@
+LICENSE (1)
+LICENSE (1):Zone.Identifier
+pyproject.toml
+healchain/__init__.py
+healchain/client.py
+healchain_sdk.egg-info/PKG-INFO
+healchain_sdk.egg-info/SOURCES.txt
+healchain_sdk.egg-info/dependency_links.txt
+healchain_sdk.egg-info/requires.txt
+healchain_sdk.egg-info/top_level.txt
+tests/test_client.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,4 @@
+
+[dev]
+pytest
+pytest-mock

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

@@ -0,0 +1 @@
+healchain

healchain_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "healchain-sdk"
+version = "0.1.0"
+description = "Python SDK for HealChain — self-healing decentralized storage via Reed-Solomon erasure coding"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "HealChain Team", email = "info@healchain.org" }]
+keywords = [
+    "healchain", "blockchain", "storage", "reed-solomon",
+    "erasure-coding", "ethereum", "arbitrum", "decentralized",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.8"
+dependencies = []   # zero dependencies — stdlib only
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-mock"]
+
+[project.urls]
+Homepage    = "https://healchain.org"
+Repository  = "https://github.com/karmaxul/ci-quantum-storage"
+"Bug Tracker" = "https://github.com/karmaxul/ci-quantum-storage/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["healchain*"]

healchain_sdk-0.1.0/setup.cfg

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

healchain_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,219 @@
+"""
+HealChain Python SDK — smoke tests
+Run: python -m pytest tests/ -v
+  or: python tests/test_client.py
+
+Set HC_API_URL env var to override the default API endpoint.
+"""
+
+import os
+import sys
+import traceback
+
+# Allow running directly without pytest
+try:
+    import pytest
+    HAS_PYTEST = True
+except ImportError:
+    HAS_PYTEST = False
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from healchain import HealChain, HealChainError
+
+API_URL = os.environ.get("HC_API_URL", "https://api.healchain.org")
+hc = HealChain(api_url=API_URL)
+
+# ── Simple test runner (no pytest required) ───────────────────────────────────
+
+passed = 0
+failed = 0
+
+def test(name):
+    """Decorator for standalone test functions."""
+    def decorator(fn):
+        global passed, failed
+        try:
+            fn()
+            print(f"  ✅ {name}")
+            passed += 1
+        except Exception as e:
+            print(f"  ❌ {name}")
+            print(f"     {e}")
+            failed += 1
+        return fn
+    return decorator
+
+def assert_eq(a, b, msg=""):
+    if a != b:
+        raise AssertionError(msg or f"{a!r} != {b!r}")
+
+def assert_true(condition, msg="Assertion failed"):
+    if not condition:
+        raise AssertionError(msg)
+
+def assert_in(key, obj, msg=""):
+    if key not in obj:
+        raise AssertionError(msg or f"{key!r} not in {obj!r}")
+
+
+# ── health() ──────────────────────────────────────────────────────────────────
+
+print(f"\nHealChain Python SDK tests — {API_URL}\n")
+print("health()")
+
+@test("returns status field")
+def _():
+    h = hc.health()
+    assert_in("status", h)
+
+@test("returns version field")
+def _():
+    h = hc.health()
+    assert_true(isinstance(h.get("version"), str), "version should be a string")
+
+
+# ── retrieve() ────────────────────────────────────────────────────────────────
+
+print("\nretrieve()")
+
+@test("retrieves record 9")
+def _():
+    r = hc.retrieve(9)
+    assert_in("record_id", r)
+    assert_true(isinstance(r["bytes"], int), "bytes should be int")
+
+@test("returns chain_id in response")
+def _():
+    r = hc.retrieve(9)
+    assert_in("chain_id", r)
+    # record 9 is on Arbitrum Sepolia
+    assert_eq(r["chain_id"], "421614", f"Expected Arbitrum chain, got {r['chain_id']}")
+
+@test("returns text field")
+def _():
+    r = hc.retrieve(9)
+    assert_true(r.get("text") is not None, "text field missing")
+
+@test("raises HealChainError for missing record")
+def _():
+    try:
+        hc.retrieve(999999)
+        raise AssertionError("Should have raised HealChainError")
+    except HealChainError as e:
+        assert_true(e.status is not None or e.code is not None,
+                    "Expected status or code on error")
+
+
+# ── list() ────────────────────────────────────────────────────────────────────
+
+print("\nlist()")
+
+@test("returns records list")
+def _():
+    result = hc.list(0, 5)
+    assert_true(isinstance(result["records"], list), "records should be a list")
+    assert_true(isinstance(result["total"], int), "total should be int")
+
+@test("respects limit parameter")
+def _():
+    result = hc.list(0, 2)
+    assert_true(len(result["records"]) <= 2,
+                f"Expected ≤2 records, got {len(result['records'])}")
+
+@test("returns pagination fields")
+def _():
+    result = hc.list(0, 5)
+    for key in ("records", "total", "pages", "page", "limit"):
+        assert_in(key, result)
+
+
+# ── get_metadata() ────────────────────────────────────────────────────────────
+
+print("\nget_metadata()")
+
+@test("returns metadata fields")
+def _():
+    m = hc.get_metadata(9)
+    for key in ("label", "original_size", "encoded_size", "data_shards", "parity_shards"):
+        assert_in(key, m)
+
+@test("label is a non-empty string")
+def _():
+    m = hc.get_metadata(9)
+    assert_true(isinstance(m["label"], str) and len(m["label"]) > 0,
+                f"Expected non-empty label, got: {m['label']!r}")
+
+
+# ── HealChainError ────────────────────────────────────────────────────────────
+
+print("\nHealChainError")
+
+@test("has status attribute")
+def _():
+    try:
+        hc.retrieve(999999)
+    except HealChainError as e:
+        assert_true(hasattr(e, "status"), "Missing status attribute")
+
+@test("has code attribute")
+def _():
+    bad = HealChain(api_url="http://localhost:99999", poll_timeout=1)
+    try:
+        bad.retrieve(0)
+    except HealChainError as e:
+        assert_eq(e.code, "NETWORK_ERROR")
+
+@test("to_hex handles str input")
+def _():
+    from healchain.client import _to_hex
+    result = _to_hex("Hello")
+    assert_true(result.startswith("0x"), "Should start with 0x")
+    assert_eq(result, "0x48656c6c6f")
+
+@test("to_hex handles bytes input")
+def _():
+    from healchain.client import _to_hex
+    result = _to_hex(b"Hello")
+    assert_eq(result, "0x48656c6c6f")
+
+@test("to_hex passes through existing hex")
+def _():
+    from healchain.client import _to_hex
+    result = _to_hex("0xdeadbeef")
+    assert_eq(result, "0xdeadbeef")
+
+
+# ── Summary ───────────────────────────────────────────────────────────────────
+
+print(f"\n{'─' * 40}")
+print(f"{passed + failed} tests: {passed} passed, {failed} failed\n")
+
+if failed > 0:
+    sys.exit(1)
+
+
+# ── pytest compatibility ──────────────────────────────────────────────────────
+
+def test_health_status():
+    h = hc.health()
+    assert "status" in h
+
+def test_retrieve_record():
+    r = hc.retrieve(9)
+    assert r["chain_id"] == "421614"
+
+def test_list_records():
+    result = hc.list(0, 5)
+    assert isinstance(result["records"], list)
+
+def test_get_metadata():
+    m = hc.get_metadata(9)
+    assert "label" in m
+
+def test_error_on_missing_record():
+    try:
+        hc.retrieve(999999)
+        assert False, "Should have raised"
+    except HealChainError:
+        pass