osintverse 0.1.0__tar.gz

osintverse-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src tests
+      - name: Test
+        run: pytest

osintverse-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  release:
+    types: [published]
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

osintverse-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.DS_Store

osintverse-0.1.0/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.

osintverse-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,102 @@
+# 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/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "osintverse"
+version = "0.1.0"
+description = "Official Python client for the OSINTverse SearchIn API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "OSINTverse", email = "hi@osintverse.com" }]
+keywords = ["osint", "searchin", "osintverse", "api"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://osintverse.com"
+Documentation = "https://osintverse.com/docs/python"
+Repository = "https://github.com/dheerajydv19/osintverse-pythonsdk"
+Issues = "https://github.com/dheerajydv19/osintverse-pythonsdk/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "respx>=0.22.0",
+    "ruff>=0.8.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.ruff.lint.isort]
+known-first-party = ["osintverse"]

osintverse-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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