blitz-api-py 0.1.0__tar.gz

blitz_api_py-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.mypy_cache/
+.pyright/
+.ruff_cache/
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# uv
+# (uv.lock IS committed; only ignore caches)
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store

blitz_api_py-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [0.1.0](https://github.com/api-blitz/blitz-api-py/compare/v0.1.0...v0.1.0) (2026-06-02)
+
+
+### Features
+
+* typed Python SDK for the Blitz API with automated releases ([5641a51](https://github.com/api-blitz/blitz-api-py/commit/5641a51b405108029bc701988e08d6210a1255f6))
+
+## Changelog
+
+All notable changes to this project are documented in this file.
+
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+and the changelog is maintained automatically by
+[release-please](https://github.com/googleapis/release-please) from
+[Conventional Commits](https://www.conventionalcommits.org/).

blitz_api_py-0.1.0/LICENSE

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

blitz_api_py-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: blitz-api-py
+Version: 0.1.0
+Summary: Typed Python SDK for the Blitz API — B2B data, search, and enrichment.
+Project-URL: Homepage, https://blitz-api.ai
+Project-URL: Documentation, https://docs.blitz-api.ai
+Project-URL: Repository, https://github.com/api-blitz/blitz-api-py
+Project-URL: Issues, https://github.com/api-blitz/blitz-api-py/issues
+Project-URL: Changelog, https://github.com/api-blitz/blitz-api-py/blob/main/CHANGELOG.md
+Author-email: Blitz API <founders@blitz-api.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: b2b,blitz,blitz-api,enrichment,gtm,linkedin,sales,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pydantic<3,>=2.13
+Requires-Dist: typing-extensions>=4.10
+Description-Content-Type: text/markdown
+
+# blitz-api-py
+
+The typed Python SDK for the [Blitz API](https://blitz-api.ai) — B2B data, search,
+and enrichment.
+
+- **Fully typed** — Pydantic v2 response models with attribute access and IDE
+  autocomplete, `TypedDict` request filters, and a shipped `py.typed` marker so
+  mypy/pyright see the types in your own code.
+- **Sync & async** — `BlitzAPI` and `AsyncBlitzAPI` over `httpx`.
+- **Resilient** — built-in client-side rate limiting, retries with backoff on
+  `429`/`5xx`, and a typed exception hierarchy.
+- **Forward-compatible** — new fields the API adds never break deserialization.
+
+> Create and manage API keys at [app.blitz-api.ai](https://app.blitz-api.ai).
+
+## Installation
+
+```bash
+pip install blitz-api-py
+# or: uv add blitz-api-py
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```python
+from blitz_api import BlitzAPI
+from blitz_api.types import Industry, JobLevel
+
+# api_key defaults to the BLITZ_API_KEY environment variable.
+with BlitzAPI() as client:
+    # Health-check the key before a batch job.
+    info = client.account.key_info()
+    print(info.valid, info.remaining_credits, info.max_requests_per_seconds)
+
+    # LinkedIn profile URL -> verified work email.
+    email = client.enrichment.email(
+        person_linkedin_url="https://www.linkedin.com/in/example-person",
+    )
+    if email.found:
+        print(email.email)
+
+    # Search people with typed, autocompleted filters.
+    people = client.search.people(
+        company={"industry": {"include": [Industry.SOFTWARE_DEVELOPMENT]}},
+        people={"job_level": [JobLevel.VP]},
+        max_results=10,
+    )
+    for person in people.results:
+        print(person.full_name, person.headline)
+```
+
+### Async
+
+```python
+import asyncio
+from blitz_api import AsyncBlitzAPI
+
+async def main() -> None:
+    async with AsyncBlitzAPI() as client:
+        result = await client.enrichment.company(
+            company_linkedin_url="https://www.linkedin.com/company/openai",
+        )
+        print(result.company.name if result.company else None)
+
+asyncio.run(main())
+```
+
+## Authentication
+
+Pass the key explicitly or via the `BLITZ_API_KEY` environment variable:
+
+```python
+client = BlitzAPI(api_key="sk_...")          # explicit
+client = BlitzAPI()                           # reads BLITZ_API_KEY
+```
+
+The key is sent in the `x-api-key` header. Never expose it in client-side code —
+always call the API from your backend.
+
+## Endpoints
+
+All methods are grouped into four namespaces:
+
+| Namespace | Methods |
+| --- | --- |
+| `client.account` | `key_info()` |
+| `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
+| `client.enrichment` | `email()`, `phone()`, `email_to_person()`, `phone_to_person()`, `company()`, `domain_to_linkedin()`, `linkedin_to_domain()` |
+| `client.utils` | `current_date()`, `company_employment_distribution()` |
+
+Every method returns a typed Pydantic model (see `blitz_api.types`). Enum-backed
+filter fields (e.g. `Industry`, `JobLevel`, `Continent`) accept either an enum
+member or a raw string.
+
+## Pagination
+
+The search methods return an **auto-paginating page**: iterate it and the SDK fetches
+each subsequent page for you. `search.people`/`search.companies` are cursor-based;
+`search.employee_finder` is page-based — both behave identically here.
+
+```python
+# Iterate every matching person across all pages — no cursor handling needed.
+for person in client.search.people(people={"job_level": ["VP"]}):
+    print(person.full_name)
+
+# Async works the same way.
+async for person in await async_client.search.people(people={"job_level": ["VP"]}):
+    ...
+
+# Bound how much you pull.
+for person in client.search.people(...).auto_paging_iter(max_items=200):
+    ...
+
+# Per-page control: inspect totals / cursors as you go.
+for page in client.search.companies(company={...}).iter_pages(max_pages=5):
+    print(page.total_results, len(page.results), page.cursor)
+
+# Or page manually.
+page = client.search.people(people={...}, max_results=50)
+print(page.results, page.cursor)
+nxt = page.get_next_page()        # None once exhausted
+```
+
+The page types (`CursorPage`, `PageNumberPage`, and their `Async*` variants) are
+exported from `blitz_api`.
+
+## Configuration
+
+```python
+client = BlitzAPI(
+    api_key=None,                 # falls back to BLITZ_API_KEY
+    base_url="https://api.blitz-api.ai",
+    timeout=30.0,                 # seconds, or an httpx.Timeout
+    max_retries=3,                # retries on 429 / 5xx / network errors
+    rate_limit_rps=5.0,           # client-side throttle; None to disable
+)
+```
+
+The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
+in any rolling second — so a single client instance stays under the API's limit (5 req/s
+by default; check your key's limit via
+`client.account.key_info().max_requests_per_seconds`). Across multiple processes you may
+still hit `429` — the retry path handles that.
+
+Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
+endpoint needs longer than the client default:
+
+```python
+client.search.people(people={"job_level": ["VP"]}, timeout=10.0)
+```
+
+## Error handling
+
+```python
+from blitz_api import (
+    BlitzError, AuthenticationError, InsufficientCreditsError,
+    NotFoundError, RateLimitError, APIStatusError, APIConnectionError,
+    APITimeoutError, APIResponseValidationError,
+)
+
+try:
+    client.enrichment.email(person_linkedin_url="...")
+except InsufficientCreditsError:
+    ...                            # 402 — out of credits
+except AuthenticationError:
+    ...                            # 401 — bad key
+except APIStatusError as err:
+    print(err.status_code, err.message, err.body)
+except APIResponseValidationError:
+    ...                            # 2xx whose body wasn't valid / didn't match the model
+except BlitzError:
+    ...                            # base class for everything this SDK raises
+```
+
+`429` and `5xx` are retried automatically (with backoff) up to `max_retries`;
+`401`/`402`/`404` raise immediately. Connect timeouts and connection errors are retried,
+but a **read timeout is not** — the server may already have processed (and billed) the
+request, so it surfaces as `APITimeoutError` rather than risking a double charge.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, the test/type/lint
+commands, the enum code generator, and the automated release process.
+
+## License
+
+[MIT](LICENSE)

blitz_api_py-0.1.0/README.md

@@ -0,0 +1,189 @@
+# blitz-api-py
+
+The typed Python SDK for the [Blitz API](https://blitz-api.ai) — B2B data, search,
+and enrichment.
+
+- **Fully typed** — Pydantic v2 response models with attribute access and IDE
+  autocomplete, `TypedDict` request filters, and a shipped `py.typed` marker so
+  mypy/pyright see the types in your own code.
+- **Sync & async** — `BlitzAPI` and `AsyncBlitzAPI` over `httpx`.
+- **Resilient** — built-in client-side rate limiting, retries with backoff on
+  `429`/`5xx`, and a typed exception hierarchy.
+- **Forward-compatible** — new fields the API adds never break deserialization.
+
+> Create and manage API keys at [app.blitz-api.ai](https://app.blitz-api.ai).
+
+## Installation
+
+```bash
+pip install blitz-api-py
+# or: uv add blitz-api-py
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```python
+from blitz_api import BlitzAPI
+from blitz_api.types import Industry, JobLevel
+
+# api_key defaults to the BLITZ_API_KEY environment variable.
+with BlitzAPI() as client:
+    # Health-check the key before a batch job.
+    info = client.account.key_info()
+    print(info.valid, info.remaining_credits, info.max_requests_per_seconds)
+
+    # LinkedIn profile URL -> verified work email.
+    email = client.enrichment.email(
+        person_linkedin_url="https://www.linkedin.com/in/example-person",
+    )
+    if email.found:
+        print(email.email)
+
+    # Search people with typed, autocompleted filters.
+    people = client.search.people(
+        company={"industry": {"include": [Industry.SOFTWARE_DEVELOPMENT]}},
+        people={"job_level": [JobLevel.VP]},
+        max_results=10,
+    )
+    for person in people.results:
+        print(person.full_name, person.headline)
+```
+
+### Async
+
+```python
+import asyncio
+from blitz_api import AsyncBlitzAPI
+
+async def main() -> None:
+    async with AsyncBlitzAPI() as client:
+        result = await client.enrichment.company(
+            company_linkedin_url="https://www.linkedin.com/company/openai",
+        )
+        print(result.company.name if result.company else None)
+
+asyncio.run(main())
+```
+
+## Authentication
+
+Pass the key explicitly or via the `BLITZ_API_KEY` environment variable:
+
+```python
+client = BlitzAPI(api_key="sk_...")          # explicit
+client = BlitzAPI()                           # reads BLITZ_API_KEY
+```
+
+The key is sent in the `x-api-key` header. Never expose it in client-side code —
+always call the API from your backend.
+
+## Endpoints
+
+All methods are grouped into four namespaces:
+
+| Namespace | Methods |
+| --- | --- |
+| `client.account` | `key_info()` |
+| `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
+| `client.enrichment` | `email()`, `phone()`, `email_to_person()`, `phone_to_person()`, `company()`, `domain_to_linkedin()`, `linkedin_to_domain()` |
+| `client.utils` | `current_date()`, `company_employment_distribution()` |
+
+Every method returns a typed Pydantic model (see `blitz_api.types`). Enum-backed
+filter fields (e.g. `Industry`, `JobLevel`, `Continent`) accept either an enum
+member or a raw string.
+
+## Pagination
+
+The search methods return an **auto-paginating page**: iterate it and the SDK fetches
+each subsequent page for you. `search.people`/`search.companies` are cursor-based;
+`search.employee_finder` is page-based — both behave identically here.
+
+```python
+# Iterate every matching person across all pages — no cursor handling needed.
+for person in client.search.people(people={"job_level": ["VP"]}):
+    print(person.full_name)
+
+# Async works the same way.
+async for person in await async_client.search.people(people={"job_level": ["VP"]}):
+    ...
+
+# Bound how much you pull.
+for person in client.search.people(...).auto_paging_iter(max_items=200):
+    ...
+
+# Per-page control: inspect totals / cursors as you go.
+for page in client.search.companies(company={...}).iter_pages(max_pages=5):
+    print(page.total_results, len(page.results), page.cursor)
+
+# Or page manually.
+page = client.search.people(people={...}, max_results=50)
+print(page.results, page.cursor)
+nxt = page.get_next_page()        # None once exhausted
+```
+
+The page types (`CursorPage`, `PageNumberPage`, and their `Async*` variants) are
+exported from `blitz_api`.
+
+## Configuration
+
+```python
+client = BlitzAPI(
+    api_key=None,                 # falls back to BLITZ_API_KEY
+    base_url="https://api.blitz-api.ai",
+    timeout=30.0,                 # seconds, or an httpx.Timeout
+    max_retries=3,                # retries on 429 / 5xx / network errors
+    rate_limit_rps=5.0,           # client-side throttle; None to disable
+)
+```
+
+The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
+in any rolling second — so a single client instance stays under the API's limit (5 req/s
+by default; check your key's limit via
+`client.account.key_info().max_requests_per_seconds`). Across multiple processes you may
+still hit `429` — the retry path handles that.
+
+Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
+endpoint needs longer than the client default:
+
+```python
+client.search.people(people={"job_level": ["VP"]}, timeout=10.0)
+```
+
+## Error handling
+
+```python
+from blitz_api import (
+    BlitzError, AuthenticationError, InsufficientCreditsError,
+    NotFoundError, RateLimitError, APIStatusError, APIConnectionError,
+    APITimeoutError, APIResponseValidationError,
+)
+
+try:
+    client.enrichment.email(person_linkedin_url="...")
+except InsufficientCreditsError:
+    ...                            # 402 — out of credits
+except AuthenticationError:
+    ...                            # 401 — bad key
+except APIStatusError as err:
+    print(err.status_code, err.message, err.body)
+except APIResponseValidationError:
+    ...                            # 2xx whose body wasn't valid / didn't match the model
+except BlitzError:
+    ...                            # base class for everything this SDK raises
+```
+
+`429` and `5xx` are retried automatically (with backoff) up to `max_retries`;
+`401`/`402`/`404` raise immediately. Connect timeouts and connection errors are retried,
+but a **read timeout is not** — the server may already have processed (and billed) the
+request, so it surfaces as `APITimeoutError` rather than risking a double charge.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, the test/type/lint
+commands, the enum code generator, and the automated release process.
+
+## License
+
+[MIT](LICENSE)

blitz_api_py-0.1.0/pyproject.toml

@@ -0,0 +1,129 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "blitz-api-py"
+dynamic = ["version"]
+description = "Typed Python SDK for the Blitz API — B2B data, search, and enrichment."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Blitz API", email = "founders@blitz-api.ai" }]
+keywords = ["blitz", "blitz-api", "b2b", "enrichment", "linkedin", "sales", "gtm", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.28,<1",
+    "pydantic>=2.13,<3",
+    "typing-extensions>=4.10",
+]
+
+[project.urls]
+Homepage = "https://blitz-api.ai"
+Documentation = "https://docs.blitz-api.ai"
+Repository = "https://github.com/api-blitz/blitz-api-py"
+Issues = "https://github.com/api-blitz/blitz-api-py/issues"
+Changelog = "https://github.com/api-blitz/blitz-api-py/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.15",
+    "mypy>=2.1",
+    "pyright>=1.1.390",
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+    "pytest-httpx>=0.35",
+    "pytest-cov>=6.0",
+    "tokenize-rt>=6.2.0",
+]
+
+[tool.hatch.version]
+path = "src/blitz_api/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/blitz_api"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/blitz_api", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests", "scripts", "examples"]
+target-version = "py310"
+# Machine-generated modules own their own formatting (a drift guard verifies them);
+# keep ruff from reformatting them. mypy/pyright still type-check them.
+#   - types/enums.py            <- scripts/gen_enums.py
+#   - *_sync.py + _sync/        <- scripts/gen_sync.py (transliterated from the async source)
+extend-exclude = [
+    "src/blitz_api/types/enums.py",
+    "src/blitz_api/_client_sync.py",
+    "src/blitz_api/_pagination_sync.py",
+    "src/blitz_api/_rate_limit_sync.py",
+    "src/blitz_api/resources/_sync",
+]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "C4", "SIM", "PIE", "RUF"]
+# RUF022: __all__ is intentionally grouped by category, not alphabetized.
+ignore = ["RUF022"]
+
+[tool.ruff.lint.per-file-ignores]
+# RUF012: `= []` defaults are safe on Pydantic models (deep-copied per instance)
+# and keep pyright strict happy (it infers the type from the field annotation).
+"src/blitz_api/types/*.py" = ["RUF012"]
+"src/blitz_api/_pagination_async.py" = ["RUF012"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["blitz_api"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unreachable = true
+warn_redundant_casts = true
+plugins = ["pydantic.mypy"]
+files = ["src", "tests", "scripts", "examples"]
+
+# tokenize-rt (used only by scripts/gen_sync.py) ships no type stubs.
+[[tool.mypy.overrides]]
+module = ["tokenize_rt"]
+ignore_missing_imports = true
+
+# The `# type: ignore[override]` on the page __aiter__ is unused in the async source
+# (BaseModel has no __aiter__) but required in the generated sync twin's __iter__.
+[[tool.mypy.overrides]]
+module = ["blitz_api._pagination_async"]
+warn_unused_ignores = false
+
+[tool.pyright]
+include = ["src", "tests", "examples"]
+pythonVersion = "3.10"
+typeCheckingMode = "strict"
+reportMissingTypeStubs = false
+# Resources intentionally call the client's internal `_request` across modules;
+# this is internal encapsulation, not a public-API typing concern (mypy allows it).
+reportPrivateUsage = false
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["."]
+addopts = "-ra"
+
+[tool.coverage.run]
+source = ["blitz_api"]
+branch = true

blitz_api_py-0.1.0/src/blitz_api/__init__.py

@@ -0,0 +1,65 @@
+"""Typed Python SDK for the Blitz API.
+
+Quickstart::
+
+    from blitz_api import BlitzAPI
+
+    client = BlitzAPI()  # reads the BLITZ_API_KEY environment variable
+    result = client.enrichment.email(
+        person_linkedin_url="https://www.linkedin.com/in/example",
+    )
+    print(result.found, result.email)
+
+See https://docs.blitz-api.ai for the full API reference.
+"""
+
+from __future__ import annotations
+
+from ._client import AsyncBlitzAPI, BlitzAPI
+from ._exceptions import (
+    APIConnectionError,
+    APIResponseValidationError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BlitzError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+)
+from ._pagination_async import AsyncCursorPage, AsyncPageNumberPage
+from ._pagination_sync import CursorPage, PageNumberPage
+from ._version import __version__
+from .types import (
+    CompanyFilter,
+    Industry,
+    PeopleFilter,
+)
+
+__all__ = [
+    "__version__",
+    # clients
+    "BlitzAPI",
+    "AsyncBlitzAPI",
+    # pagination (returned by the search.* methods)
+    "CursorPage",
+    "AsyncCursorPage",
+    "PageNumberPage",
+    "AsyncPageNumberPage",
+    # exceptions
+    "BlitzError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIResponseValidationError",
+    "APIStatusError",
+    "AuthenticationError",
+    "InsufficientCreditsError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    # commonly-used types (full set under blitz_api.types)
+    "Industry",
+    "CompanyFilter",
+    "PeopleFilter",
+]