firmendata 0.1.0__tar.gz

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

@@ -0,0 +1,91 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e '.[dev]'
+      - run: pytest -q
+      - run: ruff check .
+      - run: mypy
+        # One version is enough for type checking; the others only run tests.
+        if: matrix.python-version == '3.11'
+
+  # The SDK vendors contracts/openapi.v1.json and generates its types from it.
+  # If the committed types don't match what the vendored spec produces, the
+  # SDK is lying about the API — fail rather than ship that.
+  generated-types-are-current:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install -e '.[dev]'
+      - run: python scripts/generate_types.py
+      - name: Types match the vendored contract
+        run: |
+          if ! git diff --exit-code -- src/firmendata/types.py src/firmendata/params.py; then
+            echo "::error::Generated types are stale. Run 'python scripts/generate_types.py' and commit."
+            exit 1
+          fi
+
+  # Advisory: tells us when the live API has moved past our vendored copy.
+  # Never blocks — the SDK targets the spec it ships with, and a drifting
+  # upstream is a signal to cut a release, not a reason to fail this build.
+  upstream-drift:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push'
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - name: Compare vendored spec against production
+        run: |
+          curl -sSL https://api.firmendata.com/v1/openapi.json -o /tmp/live.json
+          python - <<'PY'
+          import json
+          live = json.load(open('/tmp/live.json'))
+          vendored = json.load(open('contracts/openapi.v1.json'))
+          lp, vp = set(live['paths']), set(vendored['paths'])
+          if lp != vp:
+              print(f"::warning::Vendored spec is out of date. "
+                    f"added={sorted(lp - vp)} removed={sorted(vp - lp)}")
+          else:
+              print("Vendored spec matches production paths.")
+          PY
+
+  secrets:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Full history so a secret committed and later removed is still found.
+          fetch-depth: 0
+      # The gitleaks CLI, not gitleaks/gitleaks-action. The scanner is MIT and
+      # free; it is the Action wrapper that requires a paid licence for
+      # organisation-owned repos, and it fails the job outright without one.
+      # Running the binary directly is the same scan with no licence.
+      - name: Scan git history for secrets
+        env:
+          GITLEAKS_VERSION: 8.30.1
+        run: |
+          curl -sSL "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" \
+            | tar xz -C /tmp gitleaks
+          /tmp/gitleaks git . --no-banner --redact --exit-code 1

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

@@ -0,0 +1,99 @@
+# Publishes to PyPI on a version tag.
+#
+# ─── AUTHENTICATION ────────────────────────────────────────────────────────
+#
+# Trusted Publishing (OIDC). There is no PyPI token anywhere — GitHub mints a
+# short-lived credential per run and PyPI verifies it came from this exact
+# repository and workflow. Nothing to rotate, nothing to leak.
+#
+# PyPI supports "pending publishers", so this works for the very first
+# release of a project that does not exist yet. (npm does not, which is why
+# the JavaScript packages take a different route on their first publish.)
+#
+# ─── ONE-TIME SETUP ────────────────────────────────────────────────────────
+#
+# On https://pypi.org/manage/account/publishing/ add a pending publisher:
+#
+#   PyPI project name:  firmendata
+#   Owner:              FirmenData
+#   Repository name:    firmendata-python
+#   Workflow name:      publish.yml
+#   Environment name:   pypi
+#
+# Then create the `pypi` environment under repo Settings → Environments. The
+# environment is not decoration: it is where you add a required reviewer, so
+# a tag push cannot publish to PyPI without a human approving the run.
+#
+# ─── RELEASING ─────────────────────────────────────────────────────────────
+#
+#   1. bump __version__ in src/firmendata/_version.py
+#   2. commit, then:  git tag 0.1.0 && git push origin 0.1.0
+#
+# A version can never be re-uploaded to PyPI, even after deletion. The build
+# is verified here before the publish step runs, and the publish step is a
+# separate job so the artifacts are inspectable if it fails.
+
+name: Publish
+
+on:
+  push:
+    tags: ['*.*.*']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - run: pip install -e '.[dev]' build twine
+
+      # A tag is not a licence to skip the tests.
+      - run: pytest -q
+      - run: mypy
+      - run: ruff check .
+
+      # The generated types must match the vendored contract, or we would
+      # ship an SDK that lies about the API.
+      - run: python scripts/generate_types.py
+      - run: git diff --exit-code -- src/firmendata/
+
+      - name: Tag must match the package version
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          PKG=$(python -c "import re,pathlib; \
+            print(re.search(r'\"([^\"]+)\"', pathlib.Path('src/firmendata/_version.py').read_text()).group(1))")
+          if [ "$TAG" != "$PKG" ]; then
+            echo "::error::Tag $TAG does not match __version__ $PKG"
+            exit 1
+          fi
+        if: github.event_name == 'push'
+
+      - run: python -m build
+      - run: twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # Required to mint the OIDC token PyPI verifies. Nothing else is needed —
+      # in particular there is no PYPI_TOKEN secret.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

firmendata-0.1.0/.gitignore

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

firmendata-0.1.0/LICENSE

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

firmendata-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.5
+Name: firmendata
+Version: 0.1.0
+Summary: Official Python client for the firmendata German company-data API
+Project-URL: Homepage, https://firmendata.com
+Project-URL: Documentation, https://api.firmendata.com/v1/docs
+Project-URL: Source, https://github.com/FirmenData/firmendata-python
+Project-URL: Issues, https://github.com/FirmenData/firmendata-python/issues
+Author-email: FirmenData <info@firmendata.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,company-data,company-register,firmendata,germany,handelsregister,kyc,ubo,unternehmensregister
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator>=0.25; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# firmendata-python
+
+Official Python client for the [firmendata](https://firmendata.com) API — data on
+**2.4 million German companies** from the Unternehmensregister and Handelsregister:
+register profiles, parsed annual financial statements, shareholder cap tables,
+UBO chains, insolvency notices and public-tender links.
+
+[![PyPI](https://img.shields.io/pypi/v/firmendata)](https://pypi.org/project/firmendata/)
+[![Python](https://img.shields.io/pypi/pyversions/firmendata)](https://pypi.org/project/firmendata/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+```bash
+pip install firmendata
+```
+
+## Try it without signing up
+
+Company-name autocomplete is free and needs **no API key**:
+
+```python
+from firmendata import FirmenData
+
+for hit in FirmenData().autocomplete("siemens")["data"]:
+    print(hit["eu_id"], hit["display_name"])
+```
+
+Keyless calls are rate limited, modestly and by address — enough to try the
+API, back a search box, or run low-volume queries. Add a key for substantially
+higher limits plus every other endpoint. On a `429`, honour `Retry-After`;
+the client already does this for you.
+
+## With an API key
+
+Create one at [firmendata.com](https://firmendata.com/de/account/api-keys) — the
+free plan includes 100 credits.
+
+```python
+from firmendata import FirmenData
+
+fd = FirmenData(api_key="firmendata_live_...")
+
+# Advanced search — filters combine with AND, lists with OR
+results = fd.search(
+    city=["Berlin", "Hamburg"],
+    revenue_min=1_000_000,
+    legal_status=["insolvent"],
+    limit=25,
+)
+
+for hit in results["data"]:
+    print(hit["display_name"], hit["address"]["city"])
+
+# Paginate
+if results["pagination"]["has_more"]:
+    next_page = fd.search(cursor=results["pagination"]["next_cursor"])
+```
+
+```python
+eu_id = "DEB1103R_HRB123456"
+
+fd.get_company(eu_id)        # full profile
+fd.get_financials(eu_id)     # multi-year statements, parsed into figures
+fd.get_shareholders(eu_id)   # cap table from the Gesellschafterliste
+fd.get_ubo(eu_id)            # beneficial owners through ownership chains
+fd.get_history(eu_id)        # chronological register history
+```
+
+### Async
+
+Same methods, same semantics:
+
+```python
+import asyncio
+from firmendata import AsyncFirmenData
+
+async def main():
+    async with AsyncFirmenData(api_key="firmendata_live_...") as fd:
+        company = await fd.get_company("DEB1103R_HRB123456")
+        print(company["display_name"])
+
+asyncio.run(main())
+```
+
+## Errors
+
+Every failure is a typed exception carrying the API's RFC 7807 problem detail,
+including a `request_id` you can quote to support.
+
+```python
+from firmendata import FirmenData, InsufficientCreditsError, RateLimitError
+
+try:
+    fd.get_ubo(eu_id)
+except InsufficientCreditsError:
+    ...                      # top up or upgrade
+except RateLimitError as e:
+    ...                      # e.retry_after is the server's own hint
+```
+
+| Exception | Status | Meaning |
+|---|---|---|
+| `AuthenticationError` | 401 | Missing/invalid key, or a keyless call used a paid feature |
+| `TokenExpiredError` | 401 | Key expired |
+| `InsufficientCreditsError` | 402 | Balance too low for this call |
+| `NotFoundError` | 404 | No such company, subscription or event |
+| `ConflictError` | 409 | Conflicts with existing state |
+| `ValidationError` | 422 | Bad parameters — see `.errors` for the fields |
+| `RateLimitError` | 429 | Retry budget exhausted — see `.retry_after` |
+| `ServerError` | 5xx | Retried automatically for idempotent calls |
+| `APIConnectionError` / `APITimeoutError` | — | No response at all |
+
+### Retries
+
+Automatic and deliberately conservative:
+
+- **429 is always retried**, on any method — the server rejects rate-limited
+  calls before the handler runs, so nothing happened and nothing was billed.
+  The server's `Retry-After` is used verbatim.
+- **5xx and connection failures are retried only for idempotent methods.** A
+  `create_subscription` that times out may already have been applied; replaying
+  it would create a second one.
+- Backoff is exponential with full jitter, so clients that trip the same limit
+  together don't all return at the same instant.
+
+Tune with `FirmenData(max_retries=...)`; `0` disables it.
+
+## Types
+
+Responses are plain dictionaries described by generated `TypedDict`s, so editors
+complete every field and `mypy` checks them — with **no pydantic dependency** to
+collide with your own. The only runtime requirement is `httpx`.
+
+Both `src/firmendata/types.py` and `src/firmendata/params.py` are generated from
+[`contracts/openapi.v1.json`](contracts/openapi.v1.json), a vendored copy of the
+published spec:
+
+```bash
+python scripts/generate_types.py
+```
+
+CI regenerates them and fails if the result differs from what is committed, so
+the SDK cannot silently drift from the API it targets.
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+pytest              # no network, no credentials
+mypy && ruff check
+```
+
+## Links
+
+- API reference — <https://api.firmendata.com/v1/docs>
+- TypeScript SDK — <https://github.com/FirmenData/firmendata-node>
+- n8n node — <https://github.com/FirmenData/n8n-nodes-firmendata>
+- MCP server (for AI agents) — `https://mcp.firmendata.com/mcp`
+- Website — <https://firmendata.com>
+
+## License
+
+MIT — see [LICENSE](LICENSE).

firmendata-0.1.0/README.md

@@ -0,0 +1,162 @@
+# firmendata-python
+
+Official Python client for the [firmendata](https://firmendata.com) API — data on
+**2.4 million German companies** from the Unternehmensregister and Handelsregister:
+register profiles, parsed annual financial statements, shareholder cap tables,
+UBO chains, insolvency notices and public-tender links.
+
+[![PyPI](https://img.shields.io/pypi/v/firmendata)](https://pypi.org/project/firmendata/)
+[![Python](https://img.shields.io/pypi/pyversions/firmendata)](https://pypi.org/project/firmendata/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+```bash
+pip install firmendata
+```
+
+## Try it without signing up
+
+Company-name autocomplete is free and needs **no API key**:
+
+```python
+from firmendata import FirmenData
+
+for hit in FirmenData().autocomplete("siemens")["data"]:
+    print(hit["eu_id"], hit["display_name"])
+```
+
+Keyless calls are rate limited, modestly and by address — enough to try the
+API, back a search box, or run low-volume queries. Add a key for substantially
+higher limits plus every other endpoint. On a `429`, honour `Retry-After`;
+the client already does this for you.
+
+## With an API key
+
+Create one at [firmendata.com](https://firmendata.com/de/account/api-keys) — the
+free plan includes 100 credits.
+
+```python
+from firmendata import FirmenData
+
+fd = FirmenData(api_key="firmendata_live_...")
+
+# Advanced search — filters combine with AND, lists with OR
+results = fd.search(
+    city=["Berlin", "Hamburg"],
+    revenue_min=1_000_000,
+    legal_status=["insolvent"],
+    limit=25,
+)
+
+for hit in results["data"]:
+    print(hit["display_name"], hit["address"]["city"])
+
+# Paginate
+if results["pagination"]["has_more"]:
+    next_page = fd.search(cursor=results["pagination"]["next_cursor"])
+```
+
+```python
+eu_id = "DEB1103R_HRB123456"
+
+fd.get_company(eu_id)        # full profile
+fd.get_financials(eu_id)     # multi-year statements, parsed into figures
+fd.get_shareholders(eu_id)   # cap table from the Gesellschafterliste
+fd.get_ubo(eu_id)            # beneficial owners through ownership chains
+fd.get_history(eu_id)        # chronological register history
+```
+
+### Async
+
+Same methods, same semantics:
+
+```python
+import asyncio
+from firmendata import AsyncFirmenData
+
+async def main():
+    async with AsyncFirmenData(api_key="firmendata_live_...") as fd:
+        company = await fd.get_company("DEB1103R_HRB123456")
+        print(company["display_name"])
+
+asyncio.run(main())
+```
+
+## Errors
+
+Every failure is a typed exception carrying the API's RFC 7807 problem detail,
+including a `request_id` you can quote to support.
+
+```python
+from firmendata import FirmenData, InsufficientCreditsError, RateLimitError
+
+try:
+    fd.get_ubo(eu_id)
+except InsufficientCreditsError:
+    ...                      # top up or upgrade
+except RateLimitError as e:
+    ...                      # e.retry_after is the server's own hint
+```
+
+| Exception | Status | Meaning |
+|---|---|---|
+| `AuthenticationError` | 401 | Missing/invalid key, or a keyless call used a paid feature |
+| `TokenExpiredError` | 401 | Key expired |
+| `InsufficientCreditsError` | 402 | Balance too low for this call |
+| `NotFoundError` | 404 | No such company, subscription or event |
+| `ConflictError` | 409 | Conflicts with existing state |
+| `ValidationError` | 422 | Bad parameters — see `.errors` for the fields |
+| `RateLimitError` | 429 | Retry budget exhausted — see `.retry_after` |
+| `ServerError` | 5xx | Retried automatically for idempotent calls |
+| `APIConnectionError` / `APITimeoutError` | — | No response at all |
+
+### Retries
+
+Automatic and deliberately conservative:
+
+- **429 is always retried**, on any method — the server rejects rate-limited
+  calls before the handler runs, so nothing happened and nothing was billed.
+  The server's `Retry-After` is used verbatim.
+- **5xx and connection failures are retried only for idempotent methods.** A
+  `create_subscription` that times out may already have been applied; replaying
+  it would create a second one.
+- Backoff is exponential with full jitter, so clients that trip the same limit
+  together don't all return at the same instant.
+
+Tune with `FirmenData(max_retries=...)`; `0` disables it.
+
+## Types
+
+Responses are plain dictionaries described by generated `TypedDict`s, so editors
+complete every field and `mypy` checks them — with **no pydantic dependency** to
+collide with your own. The only runtime requirement is `httpx`.
+
+Both `src/firmendata/types.py` and `src/firmendata/params.py` are generated from
+[`contracts/openapi.v1.json`](contracts/openapi.v1.json), a vendored copy of the
+published spec:
+
+```bash
+python scripts/generate_types.py
+```
+
+CI regenerates them and fails if the result differs from what is committed, so
+the SDK cannot silently drift from the API it targets.
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+pytest              # no network, no credentials
+mypy && ruff check
+```
+
+## Links
+
+- API reference — <https://api.firmendata.com/v1/docs>
+- TypeScript SDK — <https://github.com/FirmenData/firmendata-node>
+- n8n node — <https://github.com/FirmenData/n8n-nodes-firmendata>
+- MCP server (for AI agents) — `https://mcp.firmendata.com/mcp`
+- Website — <https://firmendata.com>
+
+## License
+
+MIT — see [LICENSE](LICENSE).