osintverse 0.1.0__py3-none-any.whl

osintverse/__init__.py

@@ -0,0 +1,57 @@
+"""Official Python client for the OSINTverse SearchIn API.
+
+This package talks to ``https://apiv1.osintverse.com`` (osintverse.com). It is
+not affiliated with other products that reuse the OSINTverse name.
+"""
+
+from osintverse._async_client import AsyncOSINTverse
+from osintverse._client import OSINTverse
+from osintverse._constants import VERSION as __version__
+from osintverse._exceptions import (
+    APIError,
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    OSINTverseError,
+    PaymentRequiredError,
+    SearchFailedError,
+    SearchRefundedError,
+    ValidationError,
+    WaitTimeoutError,
+)
+from osintverse._models import (
+    BulkSearch,
+    BulkSummary,
+    InputType,
+    InputTypePrice,
+    Provider,
+    ProviderId,
+    ProviderResult,
+    Search,
+    SearchStatus,
+)
+
+__all__ = [
+    "APIError",
+    "AsyncOSINTverse",
+    "AuthenticationError",
+    "BulkSearch",
+    "BulkSummary",
+    "ForbiddenError",
+    "InputType",
+    "InputTypePrice",
+    "NotFoundError",
+    "OSINTverse",
+    "OSINTverseError",
+    "PaymentRequiredError",
+    "Provider",
+    "ProviderId",
+    "ProviderResult",
+    "Search",
+    "SearchFailedError",
+    "SearchRefundedError",
+    "SearchStatus",
+    "ValidationError",
+    "WaitTimeoutError",
+    "__version__",
+]

osintverse/_async_client.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from osintverse._async_search import AsyncSearchResource
+from osintverse._constants import (
+    API_KEY_ENV,
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    USER_AGENT,
+)
+from osintverse._exceptions import AuthenticationError
+from osintverse._http import raise_for_status
+from osintverse._models import Provider
+
+
+class AsyncProvidersResource:
+    def __init__(self, client: AsyncOSINTverse) -> None:
+        self._client = client
+
+    async def list(self) -> list[Provider]:
+        """Return the live provider catalog via ``GET /v1/providers``."""
+        payload = await self._client.request("GET", "/v1/providers", auth=False)
+        return [Provider.model_validate(item) for item in payload]
+
+
+class AsyncOSINTverse:
+    """Async client for the OSINTverse SearchIn API.
+
+    Parameters match :class:`osintverse.OSINTverse`.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.api_key = api_key if api_key is not None else os.environ.get(API_KEY_ENV)
+        self.base_url = base_url.rstrip("/")
+        self._owns_http_client = http_client is None
+        self._http = http_client or httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={"User-Agent": USER_AGENT, "Accept": "application/json"},
+        )
+        self.providers = AsyncProvidersResource(self)
+        self.search = AsyncSearchResource(self)
+
+    async def health(self) -> dict[str, Any]:
+        """Service health check via ``GET /health``."""
+        payload = await self.request("GET", "/health", auth=False)
+        return payload if isinstance(payload, dict) else {"status": payload}
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        auth: bool = True,
+    ) -> Any:
+        headers: dict[str, str] = {}
+        if auth:
+            if not self.api_key:
+                raise AuthenticationError(
+                    f"Missing API key. Pass api_key= or set {API_KEY_ENV}.",
+                    status_code=401,
+                )
+            headers["x-api-key"] = self.api_key
+        response = await self._http.request(method, path, headers=headers, json=json)
+        raise_for_status(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    async def aclose(self) -> None:
+        if self._owns_http_client:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncOSINTverse:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()

osintverse/_async_search.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Sequence
+from typing import Any
+
+from osintverse._constants import DEFAULT_POLL_INTERVAL, DEFAULT_WAIT_TIMEOUT, TERMINAL_STATUSES
+from osintverse._exceptions import WaitTimeoutError
+from osintverse._models import BulkSearch, Search
+from osintverse._search import _raise_if_unsuccessful, _summarize
+
+
+class AsyncSearchResource:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    async def create(
+        self,
+        *,
+        provider: str,
+        input_type: str,
+        query: str,
+        premium: bool = False,
+        wait: bool = False,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        timeout: float = DEFAULT_WAIT_TIMEOUT,
+    ) -> Search:
+        """Create a SearchIn job via ``POST /v1/search``."""
+        body: dict[str, Any] = {
+            "provider": provider,
+            "input_type": input_type,
+            "query": query,
+        }
+        if premium:
+            body["premium"] = True
+        search = Search.model_validate(await self._client.request("POST", "/v1/search", json=body))
+        if wait:
+            return await self.wait(search, poll_interval=poll_interval, timeout=timeout)
+        return search
+
+    async def bulk(
+        self,
+        *,
+        input_type: str,
+        queries: Sequence[str],
+        providers: Sequence[str],
+        premium: bool = False,
+        wait: bool = False,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        timeout: float = DEFAULT_WAIT_TIMEOUT,
+    ) -> BulkSearch:
+        """Create many jobs via ``POST /v1/search/bulk``."""
+        body: dict[str, Any] = {
+            "input_type": input_type,
+            "queries": list(queries),
+            "providers": list(providers),
+        }
+        if premium:
+            body["premium"] = True
+        batch = BulkSearch.model_validate(
+            await self._client.request("POST", "/v1/search/bulk", json=body)
+        )
+        if wait:
+            return await self.wait_bulk(batch, poll_interval=poll_interval, timeout=timeout)
+        return batch
+
+    async def retrieve(self, search_id: str) -> Search:
+        """Fetch a job via ``GET /v1/search/{id}``."""
+        return Search.model_validate(await self._client.request("GET", f"/v1/search/{search_id}"))
+
+    get = retrieve
+
+    async def unlock(self, search_id: str) -> Search:
+        """Unlock remaining LeakRadar credentials via ``POST /v1/search/{id}/unlock``."""
+        return Search.model_validate(
+            await self._client.request(
+                "POST",
+                f"/v1/search/{search_id}/unlock",
+                json={"unlock_remaining": True},
+            )
+        )
+
+    async def premium(self, search_id: str) -> Search:
+        """Run OSINT Industries premium modules via ``POST /v1/search/{id}/premium``."""
+        return Search.model_validate(
+            await self._client.request(
+                "POST",
+                f"/v1/search/{search_id}/premium",
+                json={"premium": True},
+            )
+        )
+
+    async def wait(
+        self,
+        search: Search | str,
+        *,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        timeout: float = DEFAULT_WAIT_TIMEOUT,
+    ) -> Search:
+        """Poll until the job leaves ``running``, then raise on ``failed`` / ``refunded``."""
+        current = await self.retrieve(search) if isinstance(search, str) else search
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout
+        while current.status == "running":
+            if loop.time() >= deadline:
+                raise WaitTimeoutError(f"Timed out waiting for search {current.id}")
+            if poll_interval > 0:
+                await asyncio.sleep(poll_interval)
+            current = await self.retrieve(current.id)
+        return _raise_if_unsuccessful(current)
+
+    async def wait_bulk(
+        self,
+        batch: BulkSearch,
+        *,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        timeout: float = DEFAULT_WAIT_TIMEOUT,
+    ) -> BulkSearch:
+        """Poll every ``running`` job in a bulk batch to a terminal status."""
+        searches: list[Search] = []
+        for search in batch.searches:
+            if search.status == "running":
+                searches.append(
+                    await self._wait_terminal(
+                        search,
+                        poll_interval=poll_interval,
+                        timeout=timeout,
+                    )
+                )
+            else:
+                searches.append(search)
+        return batch.model_copy(update={"searches": searches, "summary": _summarize(searches)})
+
+    async def _wait_terminal(
+        self,
+        search: Search,
+        *,
+        poll_interval: float,
+        timeout: float,
+    ) -> Search:
+        current = search
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout
+        while current.status not in TERMINAL_STATUSES:
+            if loop.time() >= deadline:
+                raise WaitTimeoutError(f"Timed out waiting for search {current.id}")
+            if poll_interval > 0:
+                await asyncio.sleep(poll_interval)
+            current = await self.retrieve(current.id)
+        return current

osintverse/_client.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from osintverse._constants import (
+    API_KEY_ENV,
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    USER_AGENT,
+)
+from osintverse._exceptions import AuthenticationError
+from osintverse._http import raise_for_status
+from osintverse._models import Provider
+from osintverse._search import SearchResource
+
+
+class ProvidersResource:
+    def __init__(self, client: OSINTverse) -> None:
+        self._client = client
+
+    def list(self) -> list[Provider]:
+        """Return the live provider catalog via ``GET /v1/providers``."""
+        payload = self._client.request("GET", "/v1/providers", auth=False)
+        return [Provider.model_validate(item) for item in payload]
+
+
+class OSINTverse:
+    """Synchronous client for the OSINTverse SearchIn API.
+
+    Parameters
+    ----------
+    api_key:
+        Secret from Dashboard → API keys. Defaults to ``OSINTVERSE_API_KEY``.
+        Required for search routes; optional for ``health()`` and ``providers.list()``.
+    base_url:
+        API host. Defaults to ``https://apiv1.osintverse.com``.
+    timeout:
+        httpx timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self.api_key = api_key if api_key is not None else os.environ.get(API_KEY_ENV)
+        self.base_url = base_url.rstrip("/")
+        self._owns_http_client = http_client is None
+        self._http = http_client or httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={"User-Agent": USER_AGENT, "Accept": "application/json"},
+        )
+        self.providers = ProvidersResource(self)
+        self.search = SearchResource(self)
+
+    def health(self) -> dict[str, Any]:
+        """Service health check via ``GET /health``."""
+        payload = self.request("GET", "/health", auth=False)
+        return payload if isinstance(payload, dict) else {"status": payload}
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        auth: bool = True,
+    ) -> Any:
+        headers: dict[str, str] = {}
+        if auth:
+            if not self.api_key:
+                raise AuthenticationError(
+                    f"Missing API key. Pass api_key= or set {API_KEY_ENV}.",
+                    status_code=401,
+                )
+            headers["x-api-key"] = self.api_key
+        response = self._http.request(method, path, headers=headers, json=json)
+        raise_for_status(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    def close(self) -> None:
+        if self._owns_http_client:
+            self._http.close()
+
+    def __enter__(self) -> OSINTverse:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()

osintverse/_constants.py

@@ -0,0 +1,9 @@
+DEFAULT_BASE_URL = "https://apiv1.osintverse.com"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_POLL_INTERVAL = 2.0
+DEFAULT_WAIT_TIMEOUT = 120.0
+API_KEY_ENV = "OSINTVERSE_API_KEY"
+VERSION = "0.1.0"
+USER_AGENT = f"osintverse-python/{VERSION}"
+
+TERMINAL_STATUSES = frozenset({"completed", "failed", "refunded"})

osintverse/_exceptions.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class OSINTverseError(Exception):
+    """Base error for the OSINTverse Python SDK."""
+
+
+class APIError(OSINTverseError):
+    """HTTP error returned by the SearchIn API."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+        self.detail = message
+
+
+class AuthenticationError(APIError):
+    """Missing, invalid, disabled, or expired API key (HTTP 401)."""
+
+
+class PaymentRequiredError(APIError):
+    """Insufficient prepaid balance (HTTP 402)."""
+
+
+class ForbiddenError(APIError):
+    """Account is banned (HTTP 403)."""
+
+
+class NotFoundError(APIError):
+    """Search not found or not owned by this account (HTTP 404)."""
+
+
+class ValidationError(APIError):
+    """Invalid request body or provider/input_type pair (HTTP 422)."""
+
+
+class WaitTimeoutError(OSINTverseError):
+    """Timed out waiting for an async search to finish."""
+
+
+class SearchFailedError(OSINTverseError):
+    """Search finished with status ``failed`` (typically insufficient balance)."""
+
+    def __init__(self, search: Any) -> None:
+        message = getattr(search, "error", None) or f"Search {getattr(search, 'id', '?')} failed"
+        super().__init__(message)
+        self.search = search
+
+
+class SearchRefundedError(OSINTverseError):
+    """Search finished with status ``refunded`` after an upstream failure."""
+
+    def __init__(self, search: Any) -> None:
+        message = getattr(search, "error", None) or (
+            f"Search {getattr(search, 'id', '?')} was refunded after an upstream failure"
+        )
+        super().__init__(message)
+        self.search = search

osintverse/_http.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from osintverse._exceptions import (
+    APIError,
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    PaymentRequiredError,
+    ValidationError,
+)
+
+
+def extract_detail(response: httpx.Response) -> str:
+    try:
+        payload = response.json()
+    except ValueError:
+        text = response.text.strip()
+        return text or f"HTTP {response.status_code}"
+
+    detail = payload.get("detail") if isinstance(payload, dict) else payload
+    if isinstance(detail, str) and detail:
+        return detail
+    if isinstance(detail, list):
+        parts: list[str] = []
+        for item in detail:
+            if isinstance(item, dict):
+                loc = item.get("loc")
+                msg = item.get("msg") or str(item)
+                if loc:
+                    parts.append(f"{_format_loc(loc)}: {msg}")
+                else:
+                    parts.append(str(msg))
+            else:
+                parts.append(str(item))
+        if parts:
+            return "; ".join(parts)
+    if detail is not None:
+        return str(detail)
+    return f"HTTP {response.status_code}"
+
+
+def _format_loc(loc: Any) -> str:
+    if isinstance(loc, (list, tuple)):
+        return ".".join(str(part) for part in loc)
+    return str(loc)
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+
+    message = extract_detail(response)
+    body: Any
+    try:
+        body = response.json()
+    except ValueError:
+        body = response.text
+
+    mapping: dict[int, type[APIError]] = {
+        401: AuthenticationError,
+        402: PaymentRequiredError,
+        403: ForbiddenError,
+        404: NotFoundError,
+        422: ValidationError,
+    }
+    error_cls = mapping.get(response.status_code, APIError)
+    raise error_cls(message, status_code=response.status_code, body=body)

osintverse/_models.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+SearchStatus = Literal["pending", "running", "completed", "failed", "refunded"]
+InputType = Literal["email", "username", "phone", "domain", "name", "image", "ip"]
+ProviderId = Literal[
+    "osint-industries",
+    "leakradar-lite",
+    "leakosintbot",
+    "facecheck",
+    "picarta",
+    "predicta-search",
+    "dehashed",
+    "whoxy",
+    "whoisxml",
+    "securitytrails",
+    "snusbase",
+    "shodan",
+]
+
+
+class InputTypePrice(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    id: str
+    price_usd: str | None = None
+
+
+class Provider(BaseModel):
+    """Provider catalog row from ``GET /v1/providers``."""
+
+    model_config = ConfigDict(extra="allow")
+
+    id: str
+    name: str
+    category: str
+    max_unlocks: int | None = None
+    extra_unlock_usd_per_1k: str | None = None
+    premium_usd: str | None = None
+    input_types: list[InputTypePrice]
+
+
+class ProviderResult(BaseModel):
+    """Normalized search results from the upstream provider."""
+
+    model_config = ConfigDict(extra="allow")
+
+    sources: list[dict[str, Any]] = Field(default_factory=list)
+    matches: list[dict[str, Any]] = Field(default_factory=list)
+    raw: Any = None
+
+
+class Search(BaseModel):
+    """Search job status and results."""
+
+    model_config = ConfigDict(extra="allow")
+
+    id: str
+    status: SearchStatus
+    provider: str
+    input_type: str
+    query: str
+    cost_usd: str | None = None
+    balance_after: str | None = None
+    result: ProviderResult | None = None
+    error: str | None = None
+    poll_url: str | None = None
+    has_stored_result: bool = False
+    result_expires_at: str | None = None
+    batch_id: str | None = None
+
+    @property
+    def completed(self) -> bool:
+        return self.status == "completed"
+
+    @property
+    def running(self) -> bool:
+        return self.status == "running"
+
+
+class BulkSummary(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    completed: int = 0
+    running: int = 0
+    failed: int = 0
+    refunded: int = 0
+    pending: int = 0
+
+
+class BulkSearch(BaseModel):
+    """Bulk search batch: one :class:`Search` per (query, provider) job."""
+
+    model_config = ConfigDict(extra="allow")
+
+    batch_id: str
+    input_type: str
+    total: int
+    estimated_cost_usd: str
+    summary: BulkSummary
+    searches: list[Search]

osintverse/_search.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Sequence
+from typing import Any
+
+from osintverse._constants import DEFAULT_POLL_INTERVAL, DEFAULT_WAIT_TIMEOUT, TERMINAL_STATUSES
+from osintverse._exceptions import SearchFailedError, SearchRefundedError, WaitTimeoutError
+from osintverse._models import BulkSearch, BulkSummary, Search
+
+
+class SearchResource:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def create(
+        self,
+        *,
+        provider: str,
+        input_type: str,
+        query: str,
+        premium: bool = False,
+        wait: bool = False,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        timeout: float = DEFAULT_WAIT_TIMEOUT,
+    ) -> Search:
+        """Create a SearchIn job via ``POST /v1/search``.
+
+        Set ``wait=True`` to poll until the job is no longer ``running``.
+        Terminal ``failed`` / ``refunded`` statuses raise.
+        """
+        body: dict[str, Any] = {
+            "provider": provider,
+            "input_type": input_type,
+            "query": query,
+        }
+        if premium:
+            body["premium"] = True
+        search = Search.model_validate(self._client.request("POST", "/v1/search", json=body))
+        if wait:
+            return self.wait(search, poll_interval=poll_interval, timeout=timeout)
+        return search
+
+    def bulk(
+        self,
+        *,
+        input_type: str,
+        queries: Sequence[str],
+        providers: Sequence[str],
+        premium: bool = False,
+        wait: bool = False,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        timeout: float = DEFAULT_WAIT_TIMEOUT,
+    ) -> BulkSearch:
+        """Create many jobs via ``POST /v1/search/bulk``.
+
+        Partial success is normal. ``wait=True`` polls every ``running`` job;
+        failed or refunded jobs stay on the returned batch (inspect ``summary``).
+        """
+        body: dict[str, Any] = {
+            "input_type": input_type,
+            "queries": list(queries),
+            "providers": list(providers),
+        }
+        if premium:
+            body["premium"] = True
+        payload = self._client.request("POST", "/v1/search/bulk", json=body)
+        batch = BulkSearch.model_validate(payload)
+        if wait:
+            return self.wait_bulk(batch, poll_interval=poll_interval, timeout=timeout)
+        return batch
+
+    def retrieve(self, search_id: str) -> Search:
+        """Fetch a job via ``GET /v1/search/{id}``."""
+        return Search.model_validate(self._client.request("GET", f"/v1/search/{search_id}"))
+
+    get = retrieve
+
+    def unlock(self, search_id: str) -> Search:
+        """Unlock remaining LeakRadar credentials via ``POST /v1/search/{id}/unlock``."""
+        return Search.model_validate(
+            self._client.request(
+                "POST",
+                f"/v1/search/{search_id}/unlock",
+                json={"unlock_remaining": True},
+            )
+        )
+
+    def premium(self, search_id: str) -> Search:
+        """Run OSINT Industries premium modules via ``POST /v1/search/{id}/premium``."""
+        return Search.model_validate(
+            self._client.request(
+                "POST",
+                f"/v1/search/{search_id}/premium",
+                json={"premium": True},
+            )
+        )
+
+    def wait(
+        self,
+        search: Search | str,
+        *,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        timeout: float = DEFAULT_WAIT_TIMEOUT,
+    ) -> Search:
+        """Poll until the job leaves ``running``, then raise on ``failed`` / ``refunded``."""
+        current = self.retrieve(search) if isinstance(search, str) else search
+        deadline = time.monotonic() + timeout
+        while current.status == "running":
+            if time.monotonic() >= deadline:
+                raise WaitTimeoutError(f"Timed out waiting for search {current.id}")
+            if poll_interval > 0:
+                time.sleep(poll_interval)
+            current = self.retrieve(current.id)
+        return _raise_if_unsuccessful(current)
+
+    def wait_bulk(
+        self,
+        batch: BulkSearch,
+        *,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        timeout: float = DEFAULT_WAIT_TIMEOUT,
+    ) -> BulkSearch:
+        """Poll every ``running`` job in a bulk batch to a terminal status."""
+        searches: list[Search] = []
+        for search in batch.searches:
+            if search.status == "running":
+                searches.append(
+                    self._wait_terminal(
+                        search,
+                        poll_interval=poll_interval,
+                        timeout=timeout,
+                    )
+                )
+            else:
+                searches.append(search)
+        return batch.model_copy(update={"searches": searches, "summary": _summarize(searches)})
+
+    def _wait_terminal(
+        self,
+        search: Search,
+        *,
+        poll_interval: float,
+        timeout: float,
+    ) -> Search:
+        current = search
+        deadline = time.monotonic() + timeout
+        while current.status not in TERMINAL_STATUSES:
+            if time.monotonic() >= deadline:
+                raise WaitTimeoutError(f"Timed out waiting for search {current.id}")
+            if poll_interval > 0:
+                time.sleep(poll_interval)
+            current = self.retrieve(current.id)
+        return current
+
+
+def _raise_if_unsuccessful(search: Search) -> Search:
+    if search.status == "failed":
+        raise SearchFailedError(search)
+    if search.status == "refunded":
+        raise SearchRefundedError(search)
+    return search
+
+
+def _summarize(searches: list[Search]) -> BulkSummary:
+    counts = {"completed": 0, "running": 0, "failed": 0, "refunded": 0, "pending": 0}
+    for search in searches:
+        if search.status in counts:
+            counts[search.status] += 1
+    return BulkSummary.model_validate(counts)

osintverse-0.1.0.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: osintverse
+Version: 0.1.0
+Summary: Official Python client for the OSINTverse SearchIn API
+Project-URL: Homepage, https://osintverse.com
+Project-URL: Documentation, https://osintverse.com/docs/python
+Project-URL: Repository, https://github.com/dheerajydv19/osintverse-pythonsdk
+Project-URL: Issues, https://github.com/dheerajydv19/osintverse-pythonsdk/issues
+Author-email: OSINTverse <hi@osintverse.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,osint,osintverse,searchin
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.22.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Official Python client for the OSINTverse SearchIn API (osintverse.com).
+
+This is the **official** client for [OSINTverse](https://osintverse.com) SearchIn: one REST API for LeakRadar, OSINT Industries, Facecheck.id, SecurityTrails, and every other SearchIn provider.
+
+It talks to **`https://apiv1.osintverse.com`**. It is not affiliated with other products that reuse the OSINTverse name.
+
+## Install
+
+```bash
+pip install osintverse
+```
+
+Create an API key at [Dashboard → API keys](https://osintverse.com/dashboard/api). Keys use the `ov_` prefix and are shown only once.
+
+## Quick start
+
+```python
+from osintverse import OSINTverse
+
+client = OSINTverse()  # reads OSINTVERSE_API_KEY, or pass api_key="ov_…"
+
+providers = client.providers.list()
+search = client.search.create(
+    provider="leakradar-lite",
+    input_type="email",
+    query="user@example.com",
+    wait=True,  # poll GET /v1/search/{id} every ~2s when status is running
+)
+print(search.status, search.cost_usd, len(search.result.matches if search.result else []))
+```
+
+Async:
+
+```python
+from osintverse import AsyncOSINTverse
+
+async with AsyncOSINTverse() as client:
+    search = await client.search.create(
+        provider="leakradar-lite",
+        input_type="email",
+        query="user@example.com",
+        wait=True,
+    )
+```
+
+## Auth
+
+- Header: `x-api-key` (the SDK sets this for you)
+- Env: `OSINTVERSE_API_KEY`
+- Docs: [https://osintverse.com/docs/python](https://osintverse.com/docs/python)
+
+`GET /health` and `GET /v1/providers` do not require a key. Search routes do.
+
+## Methods
+
+| SDK | HTTP |
+| --- | --- |
+| `client.health()` | `GET /health` |
+| `client.providers.list()` | `GET /v1/providers` |
+| `client.search.create(...)` | `POST /v1/search` |
+| `client.search.bulk(...)` | `POST /v1/search/bulk` |
+| `client.search.retrieve(id)` | `GET /v1/search/{id}` |
+| `client.search.unlock(id)` | `POST /v1/search/{id}/unlock` |
+| `client.search.premium(id)` | `POST /v1/search/{id}/premium` |
+
+```python
+batch = client.search.bulk(
+    input_type="email",
+    queries=["alice@example.com", "bob@example.com"],
+    providers=["leakradar-lite", "dehashed"],
+    wait=True,
+)
+
+client.search.unlock(search.id)   # LeakRadar leftover credentials
+client.search.premium(search.id)  # OSINT Industries premium modules
+```
+
+`wait=True` on **create** raises `SearchFailedError` / `SearchRefundedError` if the job ends in `failed` or `refunded`. Bulk wait polls running jobs and returns the batch — inspect `summary` for partial success.
+
+## Errors
+
+HTTP `{ "detail": "…" }` maps to `AuthenticationError` (401), `PaymentRequiredError` (402), `ForbiddenError` (403), `NotFoundError` (404), `ValidationError` (422), and `APIError` (5xx).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src tests
+```
+
+## License
+
+MIT
+
+## Publishing
+
+CI runs lint and tests on every push. PyPI publishes from `.github/workflows/publish.yml` on `v*` tags using [Trusted Publishing](https://docs.pypi.org/trusted-publishers/).
+
+1. On PyPI, add a pending trusted publisher for project **osintverse**: GitHub owner `dheerajydv19`, repo `osintverse-pythonsdk`, workflow `publish.yml`, environment blank.
+2. Tag a release: `git tag v0.1.0 && git push origin v0.1.0`.
+

osintverse-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+osintverse/__init__.py,sha256=YX4nDRzuThuxrfZtmG_a6RqFGOV2TKP1QeVfFwAc64U,1278
+osintverse/_async_client.py,sha256=nci97X7rlyhgjgW0zUtT3WyyshkLvfM_8MFJ24Rqgnk,2886
+osintverse/_async_search.py,sha256=Lxme3_22ssH6dmbuOimUgeCfbSFF36tCQNVYq39z_8M,5287
+osintverse/_client.py,sha256=MPF114sFNY_uc_ohTylz0P-o9qxG9pypf2KqP1TQt8I,3053
+osintverse/_constants.py,sha256=WqrMCwp1G1CfpRm4WLMz2AgPtMeYu3mqCxin2-SbSP8,295
+osintverse/_exceptions.py,sha256=975jJHVRZt8y_0kW77oPBstpnAI_lDroE5wAL6CVhH0,1811
+osintverse/_http.py,sha256=NZzabTlwZqn7PkJXUqDlQDbtBG7E8o4uuz_-HgN5EEQ,1905
+osintverse/_models.py,sha256=4FChh-03-JICwg3ZjQmhgbezl1A2-V7kR1YHaU-s0L8,2412
+osintverse/_search.py,sha256=0pHqw7IzpoZ1Yfonv-zo4cyTnzJ8ejDqVMw5B4hD1K4,5905
+osintverse/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+osintverse-0.1.0.dist-info/METADATA,sha256=Qjy0TQcrQV9-iP2Pm7TBkcN2X_n3-S6H3FYl1TuyuTw,4537
+osintverse-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+osintverse-0.1.0.dist-info/licenses/LICENSE,sha256=B4m4EtnBqFo0LqIc8crXlid7zjoJm_IrQmF7HsJOikg,1067
+osintverse-0.1.0.dist-info/RECORD,,

osintverse-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

osintverse-0.1.0.dist-info/licenses/LICENSE

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