kaidn 1.0.0__tar.gz

kaidn-1.0.0/.gitignore

@@ -0,0 +1,18 @@
+# build
+dist/
+build/
+*.egg-info/
+
+# environments
+.venv/
+venv/
+
+# caches
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# local
+.env

kaidn-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing
+
+This repository is the source of truth for the Kaidn Python client. Pull requests are
+welcome here directly.
+
+## Setup
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## The gate
+
+All three must pass before a change lands. CI runs the same commands.
+
+```bash
+pytest tests -q                  # 12 tests, against a real local HTTP server
+mypy src/kaidn --strict
+ruff check src tests
+```
+
+## House rules, and the reasoning behind them
+
+**Zero runtime dependencies.** This client runs inside somebody's signup and checkout
+path. Every dependency it carries is one more thing that can break their deploy or appear
+in their vulnerability scanner. If you need something the standard library does not have,
+open an issue first, because the answer is usually to write the twenty lines.
+
+**Never drop a field we do not recognise.** Responses keep unknown keys in `.extra`, and
+`score()` passes unknown kwargs straight through. Both ends of the API refuse to discard
+data, which is what lets a signal shipped next week reach code running a year-old release.
+A change that filters the payload is a bug even when it makes the types tidier.
+
+**Python 3.9 stays supported.** It is end of life upstream and it is still what a lot of
+the shops using this are running. That is why annotations use `Optional[X]` rather than
+`X | None`: the newer form parses under `from __future__ import annotations`, but anything
+that resolves the hints at runtime still breaks on 3.9, and in a library that code belongs
+to somebody else.
+
+**Tests hit a real HTTP server, not a mock.** A mocked transport only proves the code
+calls the mock. The parts that break in someone else's environment are headers, timeouts,
+retries and error bodies, so the tests exercise those over a real socket.
+
+**Never retry a 4xx.** A bad key fails identically the second time. Retrying spends the
+caller's quota and delays the error reaching whoever can fix it.
+
+## Reporting a security issue
+
+Do not open a public issue. Email security@kaidn.io.

kaidn-1.0.0/LICENSE

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

kaidn-1.0.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.5
+Name: kaidn
+Version: 1.0.0
+Summary: Official Python client for Kaidn, the fraud and abuse scoring API.
+Project-URL: Homepage, https://kaidn.io
+Project-URL: Documentation, https://kaidn.io/docs
+Project-URL: Source, https://github.com/Kaidn-io/kaidn-python
+Project-URL: Issues, https://github.com/Kaidn-io/kaidn-python/issues
+Author-email: Kaidn <support@kaidn.io>
+License: MIT
+License-File: LICENSE
+Keywords: abuse,account-takeover,bot-detection,chargeback,device-fingerprinting,disposable-email,fraud,fraud-detection,fraud-prevention,ip-reputation,multi-accounting,proxy-detection,vpn-detection
+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.9
+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.9
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kaidn
+
+Official Python client for [Kaidn](https://kaidn.io), the fraud and abuse scoring API.
+
+Send one user action, get back `allow`, `review` or `block`, with the reasons attached.
+
+```bash
+pip install kaidn
+```
+
+```python
+from kaidn import KaidnClient
+
+client = KaidnClient()                       # reads $KAIDN_API_KEY
+
+r = client.score(event="signup", ip=ip, email=email)
+
+if r.blocked:
+    raise Denied(r.reason_text)
+```
+
+**Zero runtime dependencies.** This runs in your signup and checkout path, so every
+dependency it carried would be one more thing that can break your deploy or turn up in
+your vulnerability scanner. It uses the standard library and nothing else.
+
+Requires Python 3.9+. Server-side only: it holds your secret key, so never ship it to a
+browser. The browser half is [`@kaidn/fp`](https://www.npmjs.com/package/@kaidn/fp) and
+uses a separate publishable key.
+
+## Score an event
+
+`event` is the only required field, and the name is yours to choose. Send whatever else
+you already collect; the answer sharpens as you send more.
+
+```python
+r = client.score(
+    event="signup",
+    user_id=user.id,
+    ip=request.remote_addr,
+    email=form["email"],
+    device_id=form.get("kaidn_device_id"),   # from @kaidn/fp, if installed
+)
+
+r.verdict        # "allow" | "review" | "block"
+r.reasons        # ["datacenter_ip", "disposable_email"]
+r.reason_text    # a sentence you could send to the customer
+r.score          # 0-100. Bookkeeping, not a probability: branch on the verdict
+```
+
+Branching, with the three cases people actually use:
+
+```python
+if r.blocked:
+    return deny()                     # generic message: a specific one teaches the next attempt
+if r.needs_review:
+    create_account(hold_rewards=True) # they can use the product, they just cannot earn yet
+    flag_for_review(r.event_id, r.reason_text)
+else:
+    create_account()
+```
+
+## Read the evidence
+
+Every verdict shows its work. `key` is the config key you would edit to retune that
+check, so a decision tells you how to change it next time.
+
+```python
+for c in r.checks:
+    print(c.reason, c.weight, c.key, c.evidence)
+    # datacenter_ip 45 datacenterIp {'asn': '16509'}
+```
+
+## Recognise a returning device
+
+A browser fingerprint is not a person: on production traffic one iOS Safari fingerprint
+covers 2.30 different people. So use `resolved_id`, not `id`, and weigh it with
+`collision_risk`.
+
+```python
+d = r.device
+if d:
+    d.resolved_id                  # the identity. Link visits on this
+    d.collision_risk               # measured P(covers more than one person)
+    d.account_count                # includes fingerprint collisions
+    d.account_count_same_network   # the number you can defend to an angry user
+```
+
+Store `r.device_token` as a first-party cookie on your own domain and pass it back as
+`device_token` next time. The identity then becomes `deterministic`: remembered rather
+than inferred.
+
+## Dedupe one inbox, not one address
+
+`bob+1@gmail.com`, `b.o.b@gmail.com` and `bob@googlemail.com` are one mailbox.
+
+```python
+if r.identity and User.exists(email_canonical=r.identity.email_canonical):
+    return reject("an account already uses this inbox")
+```
+
+## Check an identifier on its own
+
+No event recorded, useful at the form or when cleaning a list.
+
+```python
+client.check.email("x9f2kq@mailinator.com").fraud_score   # 75
+client.check.ip("3.5.140.1").report.get("is_datacenter")  # True
+client.check.phone("+14155550123", country="US")
+```
+
+## Report what really happened
+
+Feedback is what sharpens scoring. `legit` marks your own false positive and never
+lowers anyone else's risk.
+
+```python
+client.label(label="chargeback", event_id=r.event_id)
+client.label(label="legit", event_id=r.event_id)
+```
+
+## Errors
+
+Everything raises `KaidnError`, with the API's own message.
+
+```python
+from kaidn import KaidnError
+
+try:
+    r = client.score(event="signup", email=email)
+except KaidnError as err:
+    if err.status == 429:
+        notify_ops("Kaidn quota exhausted")
+    raise
+```
+
+Network failures, timeouts, 429s and 5xx are retried automatically (2 extra attempts by
+default, honouring `Retry-After`). A 4xx is not: a bad key fails identically the second
+time, and retrying it just spends quota and delays the error reaching whoever can fix it.
+
+**Set a timeout and fail open.** A fraud vendor that can take down your signup form is a
+worse problem than the fraud:
+
+```python
+try:
+    r = client.score(event="signup", email=email)
+except KaidnError:
+    r = None          # create the account. Do not let our outage become yours.
+```
+
+## Fields we have not named yet
+
+Every response keeps what this version does not recognise, so a signal the API ships next
+week reaches code running the library you installed last year.
+
+```python
+r.get("a_field_added_after_this_release")
+r.device.get("some_new_signal")
+r.extra                                    # everything unrecognised
+```
+
+Requests work the same way: any extra keyword to `score()` is passed through untouched.
+
+## Configuration
+
+```python
+KaidnClient(
+    api_key="kdn_live_...",   # default: $KAIDN_API_KEY
+    base_url="https://api.kaidn.io",
+    timeout=10.0,             # seconds per attempt
+    retries=2,                # extra attempts on a transient failure
+)
+```
+
+## Links
+
+- [Docs](https://kaidn.io/docs) · [Guides](https://kaidn.io/docs/guides) · [Glossary](https://kaidn.io/glossary)
+- [Pricing](https://kaidn.io/pricing): 10,000 events a month free, no card
+
+MIT

kaidn-1.0.0/README.md

@@ -0,0 +1,179 @@
+# kaidn
+
+Official Python client for [Kaidn](https://kaidn.io), the fraud and abuse scoring API.
+
+Send one user action, get back `allow`, `review` or `block`, with the reasons attached.
+
+```bash
+pip install kaidn
+```
+
+```python
+from kaidn import KaidnClient
+
+client = KaidnClient()                       # reads $KAIDN_API_KEY
+
+r = client.score(event="signup", ip=ip, email=email)
+
+if r.blocked:
+    raise Denied(r.reason_text)
+```
+
+**Zero runtime dependencies.** This runs in your signup and checkout path, so every
+dependency it carried would be one more thing that can break your deploy or turn up in
+your vulnerability scanner. It uses the standard library and nothing else.
+
+Requires Python 3.9+. Server-side only: it holds your secret key, so never ship it to a
+browser. The browser half is [`@kaidn/fp`](https://www.npmjs.com/package/@kaidn/fp) and
+uses a separate publishable key.
+
+## Score an event
+
+`event` is the only required field, and the name is yours to choose. Send whatever else
+you already collect; the answer sharpens as you send more.
+
+```python
+r = client.score(
+    event="signup",
+    user_id=user.id,
+    ip=request.remote_addr,
+    email=form["email"],
+    device_id=form.get("kaidn_device_id"),   # from @kaidn/fp, if installed
+)
+
+r.verdict        # "allow" | "review" | "block"
+r.reasons        # ["datacenter_ip", "disposable_email"]
+r.reason_text    # a sentence you could send to the customer
+r.score          # 0-100. Bookkeeping, not a probability: branch on the verdict
+```
+
+Branching, with the three cases people actually use:
+
+```python
+if r.blocked:
+    return deny()                     # generic message: a specific one teaches the next attempt
+if r.needs_review:
+    create_account(hold_rewards=True) # they can use the product, they just cannot earn yet
+    flag_for_review(r.event_id, r.reason_text)
+else:
+    create_account()
+```
+
+## Read the evidence
+
+Every verdict shows its work. `key` is the config key you would edit to retune that
+check, so a decision tells you how to change it next time.
+
+```python
+for c in r.checks:
+    print(c.reason, c.weight, c.key, c.evidence)
+    # datacenter_ip 45 datacenterIp {'asn': '16509'}
+```
+
+## Recognise a returning device
+
+A browser fingerprint is not a person: on production traffic one iOS Safari fingerprint
+covers 2.30 different people. So use `resolved_id`, not `id`, and weigh it with
+`collision_risk`.
+
+```python
+d = r.device
+if d:
+    d.resolved_id                  # the identity. Link visits on this
+    d.collision_risk               # measured P(covers more than one person)
+    d.account_count                # includes fingerprint collisions
+    d.account_count_same_network   # the number you can defend to an angry user
+```
+
+Store `r.device_token` as a first-party cookie on your own domain and pass it back as
+`device_token` next time. The identity then becomes `deterministic`: remembered rather
+than inferred.
+
+## Dedupe one inbox, not one address
+
+`bob+1@gmail.com`, `b.o.b@gmail.com` and `bob@googlemail.com` are one mailbox.
+
+```python
+if r.identity and User.exists(email_canonical=r.identity.email_canonical):
+    return reject("an account already uses this inbox")
+```
+
+## Check an identifier on its own
+
+No event recorded, useful at the form or when cleaning a list.
+
+```python
+client.check.email("x9f2kq@mailinator.com").fraud_score   # 75
+client.check.ip("3.5.140.1").report.get("is_datacenter")  # True
+client.check.phone("+14155550123", country="US")
+```
+
+## Report what really happened
+
+Feedback is what sharpens scoring. `legit` marks your own false positive and never
+lowers anyone else's risk.
+
+```python
+client.label(label="chargeback", event_id=r.event_id)
+client.label(label="legit", event_id=r.event_id)
+```
+
+## Errors
+
+Everything raises `KaidnError`, with the API's own message.
+
+```python
+from kaidn import KaidnError
+
+try:
+    r = client.score(event="signup", email=email)
+except KaidnError as err:
+    if err.status == 429:
+        notify_ops("Kaidn quota exhausted")
+    raise
+```
+
+Network failures, timeouts, 429s and 5xx are retried automatically (2 extra attempts by
+default, honouring `Retry-After`). A 4xx is not: a bad key fails identically the second
+time, and retrying it just spends quota and delays the error reaching whoever can fix it.
+
+**Set a timeout and fail open.** A fraud vendor that can take down your signup form is a
+worse problem than the fraud:
+
+```python
+try:
+    r = client.score(event="signup", email=email)
+except KaidnError:
+    r = None          # create the account. Do not let our outage become yours.
+```
+
+## Fields we have not named yet
+
+Every response keeps what this version does not recognise, so a signal the API ships next
+week reaches code running the library you installed last year.
+
+```python
+r.get("a_field_added_after_this_release")
+r.device.get("some_new_signal")
+r.extra                                    # everything unrecognised
+```
+
+Requests work the same way: any extra keyword to `score()` is passed through untouched.
+
+## Configuration
+
+```python
+KaidnClient(
+    api_key="kdn_live_...",   # default: $KAIDN_API_KEY
+    base_url="https://api.kaidn.io",
+    timeout=10.0,             # seconds per attempt
+    retries=2,                # extra attempts on a transient failure
+)
+```
+
+## Links
+
+- [Docs](https://kaidn.io/docs) · [Guides](https://kaidn.io/docs/guides) · [Glossary](https://kaidn.io/glossary)
+- [Pricing](https://kaidn.io/pricing): 10,000 events a month free, no card
+
+MIT

kaidn-1.0.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kaidn"
+version = "1.0.0"
+description = "Official Python client for Kaidn, the fraud and abuse scoring API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Kaidn", email = "support@kaidn.io" }]
+keywords = [
+  "fraud", "fraud-detection", "fraud-prevention", "abuse", "bot-detection",
+  "device-fingerprinting", "ip-reputation", "proxy-detection", "vpn-detection",
+  "disposable-email", "multi-accounting", "account-takeover", "chargeback",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+  "Typing :: Typed",
+]
+
+# ZERO RUNTIME DEPENDENCIES, deliberately, matching @kaidn/sdk which runs on
+# built-in fetch. This client goes in a signup and checkout path, so every
+# dependency it carries is one more thing that can break somebody's deploy or
+# turn up in their vulnerability scanner. urllib is enough.
+dependencies = []
+
+[project.urls]
+Homepage = "https://kaidn.io"
+Documentation = "https://kaidn.io/docs"
+Source = "https://github.com/Kaidn-io/kaidn-python"
+Issues = "https://github.com/Kaidn-io/kaidn-python/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "mypy>=1.8", "ruff>=0.6"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kaidn"]
+
+# examples/ and tests/ ship in the REPO, so people can clone and run them, and
+# never in the wheel: nobody should download a demo as part of `pip install`.
+[tool.hatch.build.targets.sdist]
+exclude = ["examples", "tests", ".github"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true
+
+[tool.ruff]
+line-length = 100
+# 3.9 on purpose. It is EOL upstream, and it is still what a lot of the
+# rewards/affiliate shops this sells into are running. An SDK that refuses to
+# install is worse than one using Optional[] instead of `| None`, so ruff is
+# told the target rather than being allowed to suggest syntax that would break
+# those installs.
+target-version = "py39"
+
+[tool.ruff.lint]
+# "UP" is deliberately absent. With `from __future__ import annotations` ruff is
+# right that `str | None` PARSES on 3.9, but anything that resolves the hints at
+# runtime (typing.get_type_hints, pydantic, some DI frameworks) still raises
+# there. This is a library: the code that resolves our annotations belongs to
+# someone else, so we do not get to make that gamble on their behalf.
+select = ["E", "F", "W", "I", "B", "RUF"]

kaidn-1.0.0/src/kaidn/__init__.py

@@ -0,0 +1,42 @@
+"""Official Python client for `Kaidn <https://kaidn.io>`_, the fraud and abuse
+scoring API.
+
+Send one user action, get back ``allow``, ``review`` or ``block`` with the
+reasons attached::
+
+    from kaidn import KaidnClient
+
+    client = KaidnClient()                      # reads $KAIDN_API_KEY
+    r = client.score(event="signup", ip=ip, email=email)
+
+    if r.blocked:
+        raise Denied(r.reason_text)
+
+Zero runtime dependencies, on purpose: this runs in a signup path, and every
+dependency it carried would be one more thing that can break your deploy.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+from .client import KaidnClient
+from .errors import KaidnError
+from .models import Check, CheckResult, Device, Identity, Report, ScoreResult
+
+__all__ = [
+    "Check",
+    "CheckResult",
+    "Device",
+    "Identity",
+    "KaidnClient",
+    "KaidnError",
+    "Report",
+    "ScoreResult",
+]
+try:
+    # Single source of truth: pyproject.toml, read back from the installed
+    # metadata. A version literal repeated across three files is the classic way
+    # a release ships with the user-agent still reporting last month.
+    __version__ = _pkg_version("kaidn")
+except PackageNotFoundError:  # running from a source checkout, not installed
+    __version__ = "0.0.0.dev0"

kaidn-1.0.0/src/kaidn/client.py

@@ -0,0 +1,266 @@
+"""The Kaidn API client.
+
+Server-side only. It holds your secret key, so construct it in your backend and
+never ship it to a browser: the browser half is a separate publishable key.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Mapping, Optional
+
+from .errors import KaidnError
+from .models import CheckResult, ScoreResult
+
+__all__ = ["KaidnClient"]
+
+DEFAULT_BASE_URL = "https://api.kaidn.io"
+DEFAULT_TIMEOUT = 10.0
+DEFAULT_RETRIES = 2
+
+
+def _version() -> str:
+    """Read the version from package metadata rather than a second literal.
+
+    Imported lazily so a circular import at module load is impossible: the
+    package __init__ imports this module.
+    """
+    from . import __version__
+
+    return __version__
+
+
+
+
+class _Checks:
+    """``client.check.email(...)`` and friends."""
+
+    def __init__(self, client: "KaidnClient") -> None:
+        self._c = client
+
+    def email(self, email: str) -> CheckResult:
+        """Judge one address on its own, without recording an event."""
+        data = self._c._request("POST", "/v1/check/email", {"email": email})
+        return CheckResult.parse(data, "email")
+
+    def ip(self, ip: str) -> CheckResult:
+        """Judge one IP: datacenter, proxy, VPN, Tor, geolocation."""
+        return CheckResult.parse(self._c._request("POST", "/v1/check/ip", {"ip": ip}), "ip")
+
+    def phone(self, phone: str, country: Optional[str] = None) -> CheckResult:
+        """Judge one phone number: validity, VOIP, disposable, line type."""
+        body: Dict[str, Any] = {"phone": phone}
+        if country:
+            body["country"] = country
+        return CheckResult.parse(self._c._request("POST", "/v1/check/phone", body), "phone")
+
+
+class KaidnClient:
+    """Score events and run enrichment lookups against the Kaidn API.
+
+    The key is read from ``KAIDN_API_KEY`` when you do not pass one, so the
+    common case needs no arguments and no secret in your source::
+
+        from kaidn import KaidnClient
+
+        client = KaidnClient()
+        r = client.score(event="signup", ip=ip, email=email)
+        if r.blocked:
+            raise Denied(r.reason_text)
+
+    :param api_key: your secret key. Defaults to ``$KAIDN_API_KEY``.
+    :param base_url: override the API host.
+    :param timeout: seconds per attempt. Default 10.
+    :param retries: extra attempts on a transient failure. Default 2.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        retries: int = DEFAULT_RETRIES,
+    ) -> None:
+        key = api_key or os.environ.get("KAIDN_API_KEY")
+        if not key:
+            raise ValueError(
+                "KaidnClient: no API key. Pass api_key=... or set KAIDN_API_KEY. "
+                "Get one free at https://kaidn.io/register"
+            )
+        # A publishable key in a server client is a common and confusing
+        # mistake: it cannot score, so the failure would arrive later as an
+        # opaque 401. Say so now, while the traceback still points here.
+        if key.startswith("pk_"):
+            raise ValueError(
+                "KaidnClient: that looks like a publishable tracker key (pk_...), which can only "
+                "send fingerprints from a browser. This client needs your SECRET key."
+            )
+        self._api_key = key
+        self._base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._timeout = timeout
+        self._retries = retries
+        self.check = _Checks(self)
+
+    # ---- scoring ---------------------------------------------------------
+
+    def score(
+        self,
+        *,
+        event: str,
+        user_id: Optional[str] = None,
+        ip: Optional[str] = None,
+        email: Optional[str] = None,
+        phone: Optional[str] = None,
+        device_id: Optional[str] = None,
+        device_token: Optional[str] = None,
+        event_country: Optional[str] = None,
+        ip_country: Optional[str] = None,
+        **extra: Any,
+    ) -> ScoreResult:
+        """Score one thing that just happened.
+
+        ``event`` is the only required field and the name is yours to choose:
+        ``"signup"``, ``"login"``, ``"cashout"``, ``"trial_start"``. Send
+        whatever else you already collect; the answer sharpens as you send more.
+
+        ``**extra`` is passed through untouched, so a field the API gains later
+        works without waiting for a release of this library.
+        """
+        body: Dict[str, Any] = {"event": event}
+        for k, v in (
+            ("user_id", user_id), ("ip", ip), ("email", email), ("phone", phone),
+            ("device_id", device_id), ("device_token", device_token),
+            ("event_country", event_country), ("ip_country", ip_country),
+        ):
+            if v is not None:
+                body[k] = v
+        body.update(extra)
+        return ScoreResult.parse(self._request("POST", "/v1/score", body))
+
+    # ---- feedback, which is what sharpens the shared graph ----------------
+
+    def label(
+        self,
+        *,
+        label: str,
+        event_id: Optional[str] = None,
+        note: Optional[str] = None,
+        **extra: Any,
+    ) -> Dict[str, Any]:
+        """Report the real outcome: ``"fraud"``, ``"chargeback"`` or ``"legit"``.
+
+        ``legit`` marks your own false positive. It suppresses that entity for
+        you and never lowers anyone else's risk.
+        """
+        body: Dict[str, Any] = {"label": label}
+        if event_id:
+            body["event_id"] = event_id
+        if note:
+            body["note"] = note
+        body.update(extra)
+        return self._request("POST", "/v1/label", body)
+
+    # ---- reading your own data -------------------------------------------
+
+    def events(self, *, limit: Optional[int] = None, offset: Optional[int] = None,
+               verdict: Optional[str] = None, event: Optional[str] = None) -> Dict[str, Any]:
+        """Newest-first list of what you have scored."""
+        return self._request("GET", "/v1/events", query={
+            "limit": limit, "offset": offset, "verdict": verdict, "event": event,
+        })
+
+    def stats(self, window_hours: Optional[int] = None) -> Dict[str, Any]:
+        """Totals by verdict, average score, and the top reason codes."""
+        return self._request("GET", "/v1/stats", query={"window_hours": window_hours})
+
+    def health(self) -> Dict[str, Any]:
+        """Public liveness plus the size of every loaded intel dataset."""
+        return self._request("GET", "/v1/health")
+
+    # ---- transport -------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Mapping[str, Any]] = None,
+        query: Optional[Mapping[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        url = self._base_url + path
+        if query:
+            clean = {k: str(v) for k, v in query.items() if v is not None and v != ""}
+            if clean:
+                url += "?" + urllib.parse.urlencode(clean)
+
+        payload = json.dumps(body).encode() if body is not None else None
+        headers = {
+            "x-api-key": self._api_key,
+            "user-agent": f"kaidn-python/{_version()}",
+            "accept": "application/json",
+        }
+        if payload is not None:
+            headers["content-type"] = "application/json"
+
+        last: Optional[KaidnError] = None
+        for attempt in range(self._retries + 1):
+            req = urllib.request.Request(url, data=payload, headers=headers, method=method)
+            try:
+                with urllib.request.urlopen(req, timeout=self._timeout) as res:
+                    raw = res.read().decode("utf-8") or "{}"
+                    return json.loads(raw)  # type: ignore[no-any-return]
+            except urllib.error.HTTPError as err:
+                status = err.code
+                message, parsed = _read_error(err)
+                error = KaidnError(status, message, parsed)
+                retry_after = _retry_after(err.headers.get("Retry-After"))
+            except Exception as err:
+                # status 0 keeps "the request never got an answer" distinct from
+                # "the server answered and said no", which are different bugs.
+                error = KaidnError(0, str(err) or "network error")
+                retry_after = None
+
+            if error.retryable and attempt < self._retries:
+                last = error
+                time.sleep(retry_after if retry_after is not None else _backoff(attempt))
+                continue
+            raise error
+
+        raise last or KaidnError(0, "request failed")  # pragma: no cover
+
+
+def _read_error(err: "urllib.error.HTTPError") -> "tuple[str, Optional[Any]]":
+    """Prefer the API's own ``{"error": ...}`` string over a generic status."""
+    try:
+        text = err.read().decode("utf-8")
+    except Exception:
+        text = ""
+    try:
+        parsed = json.loads(text)
+        if isinstance(parsed, dict) and isinstance(parsed.get("error"), str):
+            return parsed["error"], parsed
+        return (text[:300] or f"request failed ({err.code})"), parsed
+    except Exception:
+        return (text[:300] or f"request failed ({err.code})"), None
+
+
+def _retry_after(header: Optional[str]) -> Optional[float]:
+    """Honour Retry-After when the server sends one. It knows better than we do."""
+    if not header:
+        return None
+    try:
+        return max(0.0, float(header))
+    except ValueError:
+        return None
+
+
+def _backoff(attempt: int) -> float:
+    """Exponential with jitter. The jitter matters: without it, every client
+    that got rate-limited at the same moment retries at the same moment."""
+    return float(0.25 * (2**attempt) + random.uniform(0, 0.1))

kaidn-1.0.0/src/kaidn/errors.py

@@ -0,0 +1,45 @@
+"""The one exception this client raises."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class KaidnError(Exception):
+    """Raised on any non-2xx response, and on a network or timeout failure with
+    ``status = 0``.
+
+    ``message`` is the API's ``{"error": ...}`` string when it sent one, so the
+    thing a developer reads first is the thing the server actually said.
+
+    Quota exhaustion arrives as ``status == 429``. Check for it explicitly if
+    you want to prompt an upgrade rather than back off::
+
+        try:
+            r = client.score(event="signup", email=email)
+        except KaidnError as err:
+            if err.status == 429:
+                notify_ops("Kaidn quota exhausted")
+            raise
+    """
+
+    def __init__(self, status: int, message: str, body: Optional[Any] = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.message = message
+        #: the parsed JSON error body, when the response had one
+        self.body = body
+
+    @property
+    def retryable(self) -> bool:
+        """True when the failure is transient and worth retrying: a network
+        error, a timeout, a rate limit, or a 5xx.
+
+        A 4xx is not retryable. A bad key or a malformed body will fail exactly
+        the same way the second time, and retrying it just spends your quota
+        and delays the error reaching whoever can fix it.
+        """
+        return self.status == 0 or self.status == 429 or self.status >= 500
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return f"KaidnError(status={self.status}, message={self.message!r})"

kaidn-1.0.0/src/kaidn/models.py

@@ -0,0 +1,197 @@
+"""Response models.
+
+## Why these are dataclasses and not dicts
+
+A dict gives you no autocomplete and no typo protection: ``r["verdcit"]`` is a
+``KeyError`` at 3am rather than a red squiggle. Every response here is a
+dataclass with real attributes.
+
+## Why they keep unknown fields
+
+Every response schema on the Kaidn API sets ``additionalProperties: true``,
+because a schema that omits a field would silently delete it from the wire.
+These models take the same position from the other end: an unrecognised key is
+kept in ``.extra`` rather than dropped.
+
+That matters more than it sounds. It means a field added to the API next week
+reaches your code on the version of this library you installed last year, and
+an SDK upgrade is never the thing standing between you and a new signal.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, fields
+from typing import Any, Dict, List, Optional, Type, TypeVar
+
+T = TypeVar("T", bound="_Model")
+
+
+@dataclass
+class _Model:
+    """Base: builds from a dict, keeps whatever it did not recognise."""
+
+    #: keys the server sent that this version of the library does not name yet
+    extra: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def _from(cls: Type[T], data: Optional[Dict[str, Any]]) -> Optional[T]:
+        if data is None:
+            return None
+        known = {f.name for f in fields(cls)} - {"extra"}
+        kwargs = {k: v for k, v in data.items() if k in known}
+        extra = {k: v for k, v in data.items() if k not in known}
+        obj = cls(**kwargs)
+        obj.extra = extra
+        return obj
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Read a field by name, including one this version does not know about.
+
+        ``r.device.get("some_new_signal")`` works the day the API ships it.
+        """
+        if key in {f.name for f in fields(self)}:
+            return getattr(self, key)
+        return self.extra.get(key, default)
+
+
+@dataclass
+class Check(_Model):
+    """One check that fired, with the numbers behind it."""
+
+    check: str = ""
+    #: the config key that sets this check's weight, so a verdict tells you
+    #: exactly what to edit in /v1/config to change it next time
+    key: Optional[str] = None
+    weight: float = 0.0
+    reason: str = ""
+    message: str = ""
+    #: free-form: each check attaches whatever it measured
+    evidence: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Device(_Model):
+    """Server-side device profile. Present when the event carried a device_id."""
+
+    #: the RAW browser fingerprint. Useful for debugging, and it COLLIDES across
+    #: unrelated people, so never treat it as an identity. Use resolved_id.
+    id: str = ""
+    #: the resolved device identity. This is the one that identifies a browser.
+    resolved_id: Optional[str] = None
+    #: "deterministic" (a device token was replayed) or "probabilistic"
+    resolution: Optional[str] = None
+    #: 1 = device token, 2 = fingerprint + network, 3 = neither, links nothing
+    resolution_rung: Optional[int] = None
+    #: measured P(this identity covers more than one person), 0-1
+    collision_risk: Optional[float] = None
+    #: whether collision_risk was measured for this platform, or is the average
+    risk_measured: Optional[bool] = None
+    #: set when a token was sent but unusable: usually a broken integration
+    token_rejected: Optional[str] = None
+    #: accounts on the raw fingerprint. Includes collisions, so it is NOT a
+    #: person count. Prefer the field below when you have to justify a decision.
+    account_count: int = 0
+    #: accounts on this fingerprint AND this network. The number you can defend.
+    account_count_same_network: Optional[int] = None
+    distinct_ips: int = 0
+    unique: bool = True
+    connection_type: Optional[str] = None
+    os: Optional[str] = None
+    browser: Optional[str] = None
+    mobile: Optional[bool] = None
+    is_headless: Optional[bool] = None
+    ua_consistent: Optional[bool] = None
+    is_emulated: Optional[bool] = None
+    is_noise_injected: Optional[bool] = None
+    is_tampered: Optional[bool] = None
+    is_context_mismatch: Optional[bool] = None
+    is_engine_mismatch: Optional[bool] = None
+    is_os_mismatch: Optional[bool] = None
+    timezone: Optional[str] = None
+    ja4: bool = False
+    ja4_known_tool: Optional[str] = None
+
+
+@dataclass
+class Identity(_Model):
+    """Dedupe keys derived from the event's identifiers."""
+
+    #: every alias of one mailbox collapses to this. Dedupe on it and one inbox
+    #: can no longer register as several people.
+    email_canonical: str = ""
+    email_is_aliased: bool = False
+    email_alias_tricks: List[str] = field(default_factory=list)
+
+
+@dataclass
+class ScoreResult(_Model):
+    """What POST /v1/score returns."""
+
+    event_id: str = ""
+    score: float = 0.0
+    #: "allow", "review" or "block". Branch on this.
+    verdict: str = "allow"
+    #: stable machine-matchable names. Branch on these rather than the score.
+    reasons: List[str] = field(default_factory=list)
+    #: the same finding as a sentence, clear enough to send to a customer
+    reason_text: str = ""
+    checks: List[Check] = field(default_factory=list)
+    device: Optional[Device] = None
+    #: store as a first-party cookie on YOUR domain, send back next time
+    device_token: Optional[str] = None
+    identity: Optional[Identity] = None
+    #: dropped or malformed optional fields: reported, not rejected
+    warnings: List[str] = field(default_factory=list)
+
+    @property
+    def blocked(self) -> bool:
+        return self.verdict == "block"
+
+    @property
+    def needs_review(self) -> bool:
+        return self.verdict == "review"
+
+    @classmethod
+    def parse(cls, data: Dict[str, Any]) -> "ScoreResult":
+        r = cls._from(data)
+        assert r is not None
+        r.checks = [c for c in (Check._from(c) for c in data.get("checks", [])) if c]
+        r.device = Device._from(data.get("device"))
+        r.identity = Identity._from(data.get("identity"))
+        return r
+
+
+@dataclass
+class Report(_Model):
+    """An enrichment report from /v1/check/*.
+
+    Deliberately open: the field set is large, differs per identifier, and grows
+    as intel sources are added. ``fraud_score`` is the only guarantee, and
+    everything else is reachable through ``.get()`` or ``.extra``.
+    """
+
+    fraud_score: float = 0.0
+
+
+@dataclass
+class CheckResult(_Model):
+    """What POST /v1/check/{email,ip,phone} returns."""
+
+    report: Optional[Report] = None
+    reputation: Dict[str, Any] = field(default_factory=dict)
+    summary: str = ""
+
+    @classmethod
+    def parse(cls, data: Dict[str, Any], kind: str) -> "CheckResult":
+        obj = cls(
+            report=Report._from(data.get(kind) or {}),
+            reputation=data.get("reputation", {}),
+            summary=data.get("summary", ""),
+        )
+        obj.extra = {k: v for k, v in data.items() if k not in {kind, "reputation", "summary"}}
+        return obj
+
+    @property
+    def fraud_score(self) -> float:
+        """Shortcut for the one field every report guarantees."""
+        return self.report.fraud_score if self.report else 0.0