domainkits 0.1.0__tar.gz

domainkits-0.1.0/LICENSE

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

domainkits-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: domainkits
+Version: 0.1.0
+Summary: Python client for the DomainKits REST API. Search expiring, newly registered, aged, active, deleted and marketplace domains, plus WHOIS, DNS, Certificate Transparency and trends.
+Author-email: DomainKits <info@domainkits.com>
+License-Expression: MIT
+Project-URL: Homepage, https://domainkits.com/dev
+Project-URL: Documentation, https://domainkits.com/dev/api-docs
+Project-URL: Repository, https://github.com/ABTdomain/domainkits-sdk-py
+Keywords: domain,domain-search,expired-domains,newly-registered-domains,whois,dns,certificate-transparency,domainkits
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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 :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# domainkits
+
+Python client for the [DomainKits](https://domainkits.com) REST API.
+
+DomainKits is one API with a shared key across every endpoint. This package covers all of them, six domain search types, WHOIS, DNS, reverse nameserver, Certificate Transparency, safety, trends and bulk download, with automatic paging and structured quota errors. No dependencies.
+
+## Requirements
+
+The REST API is for Premium and Platinum accounts; unauthenticated requests are rejected with 401. Keys start with `dk_` and come from [domainkits.com](https://domainkits.com/pricing).
+
+## Install
+
+```bash
+pip install domainkits
+```
+
+## Usage
+
+```python
+import os
+from domainkits import DomainKits
+
+dk = DomainKits(os.environ["DOMAINKITS_API_KEY"])
+
+result = dk.expired.list(
+    keyword="clinic",
+    tld="com",
+    length="5-10",
+    no_number=True,
+    no_hyphen=True,
+)
+
+print(f"{result['total']} matches")
+for d in result["data"]:
+    print(d["domain"], d["age"], d["status"])
+```
+
+### Paging
+
+A single request returns at most 500 results. `paginate` walks the whole result set for you:
+
+```python
+for domain in dk.expired.paginate(keyword="clinic", tld="com"):
+    print(domain["domain"])
+```
+
+It stops when the result set is exhausted. Break out of the loop whenever you have enough; no further requests are made.
+
+### Export
+
+`export` pulls up to 50,000 rows as CSV in one request:
+
+```python
+csv = dk.expired.export(tld="com", status="pending_delete")
+```
+
+This runs on a separate, much smaller quota, 10 per day and 100 per month on Premium, 3 and 9 during the trial. It is for occasional bulk pulls, not for a scheduled job. The export also returns fewer columns than paged mode: `registered_date` is the year only, and `age` is omitted.
+
+50,000 is a cap, not a promise of completeness. Browsing `.com` matched 4,847,613 expiring domains on 27 July 2026, so an unfiltered export returns the first 50,000. Narrow the query if you need the result set to fit.
+
+## Search types
+
+| Attribute | What it searches |
+|---|---|
+| `dk.expired` | Domains in the deletion cycle: expired, redemption, pending delete |
+| `dk.nrds` | Newly registered domains, last 60 days |
+| `dk.aged` | Domains with 5 to 20+ years of registration history |
+| `dk.active` | Currently registered domains |
+| `dk.deleted` | Dropped domains (requires `keyword`) |
+| `dk.market` | Domains listed for sale on marketplaces |
+
+Each has `list`, `paginate` and `export`. Filters are passed as keyword arguments and match the REST parameter names: an expired result carries `status`, an NRD result carries `expiry_date`, a market result carries `marketplace`.
+
+## Other endpoints
+
+```python
+dk.whois("example.com")
+dk.dns("example.com")
+dk.safety("example.com")
+dk.ns_reverse("ns1.example.com", tld="com")
+dk.tld_check("yourbrand")
+dk.typosquat("example.com")
+dk.ip_lookup("8.8.8.8")
+dk.registrar("godaddy")
+dk.status_guide("clientHold")
+dk.monitor_changes(tld="com", reason="transfer")
+dk.ct_subdomains("example.com")
+dk.ct_certs(domain="example.com")
+dk.ct_search("example")
+dk.tld_trends("newly", tld="com")
+dk.keyword_trends("hot")
+dk.usage()
+dk.search_status()
+```
+
+## Coverage
+
+**gTLDs only** for the domain search endpoints. The index covers generic TLDs: `.com`, `.net`, `.org`, `.info`, `.biz`, `.xyz`, `.online`, `.site`, `.top`, `.club`, `.live`, `.app`, `.dev` and others. Country-code TLDs are not indexed: a query for `.de`, `.io`, `.co` or `.us` returns an empty result set, not an error.
+
+`whois`, `dns`, `safety`, `ip_lookup` and the Certificate Transparency endpoints work on any domain, ccTLDs included.
+
+**No PII.** Responses contain no personal data. WHOIS results are limited to registrar, dates, status codes and nameservers; registrant names, emails, addresses and phone numbers are not returned.
+
+## Errors
+
+```python
+from domainkits import DomainKits, DomainKitsError, RateLimitError, AuthError
+
+try:
+    dk.expired.export(tld="com")
+except RateLimitError as error:
+    print(f"Quota exhausted. Retry in {error.retry_after_ms}ms")
+    print(error.rate_limit)
+except AuthError:
+    print("Key rejected, check your plan tier")
+except DomainKitsError as error:
+    print(error.status, error)
+```
+
+Every error carries the `x-ratelimit-limit`, `x-ratelimit-remaining` and `x-ratelimit-reset` values as a parsed `rate_limit` object. `RateLimitError.retry_after_ms` tells you how long until the window resets.
+
+429 and 5xx responses are retried automatically, twice by default, waiting until the rate-limit window resets when that is under two minutes. Set `max_retries=0` to handle it yourself.
+
+## Options
+
+```python
+dk = DomainKits(
+    api_key=os.environ["DOMAINKITS_API_KEY"],
+    timeout=60.0,
+    max_retries=2,
+    base_url="https://premium-api.domainkits.com/api/v1",
+)
+```
+
+## Quotas
+
+Call `usage()` for the live picture on your account; every endpoint reports its own per-minute, daily and monthly allowance alongside what you have already spent.
+
+Daily quotas reset at 00:00 UTC, monthly quotas on the 1st. Current limits: [domainkits.com/dev/api-docs](https://domainkits.com/dev/api-docs).
+
+## Resources
+
+- [DomainKits API reference](https://domainkits.com/dev/api-docs)
+- [@domainkits/sdk](https://www.npmjs.com/package/@domainkits/sdk), the same API for TypeScript
+- [n8n-nodes-domainkits](https://www.npmjs.com/package/n8n-nodes-domainkits), the same API for n8n
+
+## License
+
+MIT

domainkits-0.1.0/README.md

@@ -0,0 +1,149 @@
+# domainkits
+
+Python client for the [DomainKits](https://domainkits.com) REST API.
+
+DomainKits is one API with a shared key across every endpoint. This package covers all of them, six domain search types, WHOIS, DNS, reverse nameserver, Certificate Transparency, safety, trends and bulk download, with automatic paging and structured quota errors. No dependencies.
+
+## Requirements
+
+The REST API is for Premium and Platinum accounts; unauthenticated requests are rejected with 401. Keys start with `dk_` and come from [domainkits.com](https://domainkits.com/pricing).
+
+## Install
+
+```bash
+pip install domainkits
+```
+
+## Usage
+
+```python
+import os
+from domainkits import DomainKits
+
+dk = DomainKits(os.environ["DOMAINKITS_API_KEY"])
+
+result = dk.expired.list(
+    keyword="clinic",
+    tld="com",
+    length="5-10",
+    no_number=True,
+    no_hyphen=True,
+)
+
+print(f"{result['total']} matches")
+for d in result["data"]:
+    print(d["domain"], d["age"], d["status"])
+```
+
+### Paging
+
+A single request returns at most 500 results. `paginate` walks the whole result set for you:
+
+```python
+for domain in dk.expired.paginate(keyword="clinic", tld="com"):
+    print(domain["domain"])
+```
+
+It stops when the result set is exhausted. Break out of the loop whenever you have enough; no further requests are made.
+
+### Export
+
+`export` pulls up to 50,000 rows as CSV in one request:
+
+```python
+csv = dk.expired.export(tld="com", status="pending_delete")
+```
+
+This runs on a separate, much smaller quota, 10 per day and 100 per month on Premium, 3 and 9 during the trial. It is for occasional bulk pulls, not for a scheduled job. The export also returns fewer columns than paged mode: `registered_date` is the year only, and `age` is omitted.
+
+50,000 is a cap, not a promise of completeness. Browsing `.com` matched 4,847,613 expiring domains on 27 July 2026, so an unfiltered export returns the first 50,000. Narrow the query if you need the result set to fit.
+
+## Search types
+
+| Attribute | What it searches |
+|---|---|
+| `dk.expired` | Domains in the deletion cycle: expired, redemption, pending delete |
+| `dk.nrds` | Newly registered domains, last 60 days |
+| `dk.aged` | Domains with 5 to 20+ years of registration history |
+| `dk.active` | Currently registered domains |
+| `dk.deleted` | Dropped domains (requires `keyword`) |
+| `dk.market` | Domains listed for sale on marketplaces |
+
+Each has `list`, `paginate` and `export`. Filters are passed as keyword arguments and match the REST parameter names: an expired result carries `status`, an NRD result carries `expiry_date`, a market result carries `marketplace`.
+
+## Other endpoints
+
+```python
+dk.whois("example.com")
+dk.dns("example.com")
+dk.safety("example.com")
+dk.ns_reverse("ns1.example.com", tld="com")
+dk.tld_check("yourbrand")
+dk.typosquat("example.com")
+dk.ip_lookup("8.8.8.8")
+dk.registrar("godaddy")
+dk.status_guide("clientHold")
+dk.monitor_changes(tld="com", reason="transfer")
+dk.ct_subdomains("example.com")
+dk.ct_certs(domain="example.com")
+dk.ct_search("example")
+dk.tld_trends("newly", tld="com")
+dk.keyword_trends("hot")
+dk.usage()
+dk.search_status()
+```
+
+## Coverage
+
+**gTLDs only** for the domain search endpoints. The index covers generic TLDs: `.com`, `.net`, `.org`, `.info`, `.biz`, `.xyz`, `.online`, `.site`, `.top`, `.club`, `.live`, `.app`, `.dev` and others. Country-code TLDs are not indexed: a query for `.de`, `.io`, `.co` or `.us` returns an empty result set, not an error.
+
+`whois`, `dns`, `safety`, `ip_lookup` and the Certificate Transparency endpoints work on any domain, ccTLDs included.
+
+**No PII.** Responses contain no personal data. WHOIS results are limited to registrar, dates, status codes and nameservers; registrant names, emails, addresses and phone numbers are not returned.
+
+## Errors
+
+```python
+from domainkits import DomainKits, DomainKitsError, RateLimitError, AuthError
+
+try:
+    dk.expired.export(tld="com")
+except RateLimitError as error:
+    print(f"Quota exhausted. Retry in {error.retry_after_ms}ms")
+    print(error.rate_limit)
+except AuthError:
+    print("Key rejected, check your plan tier")
+except DomainKitsError as error:
+    print(error.status, error)
+```
+
+Every error carries the `x-ratelimit-limit`, `x-ratelimit-remaining` and `x-ratelimit-reset` values as a parsed `rate_limit` object. `RateLimitError.retry_after_ms` tells you how long until the window resets.
+
+429 and 5xx responses are retried automatically, twice by default, waiting until the rate-limit window resets when that is under two minutes. Set `max_retries=0` to handle it yourself.
+
+## Options
+
+```python
+dk = DomainKits(
+    api_key=os.environ["DOMAINKITS_API_KEY"],
+    timeout=60.0,
+    max_retries=2,
+    base_url="https://premium-api.domainkits.com/api/v1",
+)
+```
+
+## Quotas
+
+Call `usage()` for the live picture on your account; every endpoint reports its own per-minute, daily and monthly allowance alongside what you have already spent.
+
+Daily quotas reset at 00:00 UTC, monthly quotas on the 1st. Current limits: [domainkits.com/dev/api-docs](https://domainkits.com/dev/api-docs).
+
+## Resources
+
+- [DomainKits API reference](https://domainkits.com/dev/api-docs)
+- [@domainkits/sdk](https://www.npmjs.com/package/@domainkits/sdk), the same API for TypeScript
+- [n8n-nodes-domainkits](https://www.npmjs.com/package/n8n-nodes-domainkits), the same API for n8n
+
+## License
+
+MIT

domainkits-0.1.0/domainkits/__init__.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from typing import Any, Iterator
+
+from .client import (
+    AuthError,
+    DomainKitsClient,
+    DomainKitsError,
+    RateLimit,
+    RateLimitError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "DomainKits",
+    "DomainKitsError",
+    "RateLimitError",
+    "AuthError",
+    "RateLimit",
+    "SearchResource",
+]
+
+MAX_LIMIT = 500
+
+
+class SearchResource:
+    def __init__(self, client: DomainKitsClient, path: str):
+        self._client = client
+        self._path = path
+
+    def list(self, **params: Any) -> dict[str, Any]:
+        return self._client.request_list(self._path, params)
+
+    def paginate(self, page_size: int = MAX_LIMIT, **params: Any) -> Iterator[dict[str, Any]]:
+        offset = int(params.pop("offset", 0) or 0)
+        limit = min(page_size, MAX_LIMIT)
+        while True:
+            result = self._client.request_list(self._path, {**params, "limit": limit, "offset": offset})
+            data = result["data"]
+            yield from data
+            offset += len(data)
+            if not data or len(data) < limit or offset >= result["total"]:
+                return
+
+    def export(self, **params: Any) -> str:
+        _, _, body = self._client.request_raw(self._path, {**params, "export": "csv"})
+        return body.decode("utf-8")
+
+
+class DomainKits:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str | None = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+    ):
+        self._client = DomainKitsClient(api_key, base_url=base_url, timeout=timeout, max_retries=max_retries)
+
+        self.expired = SearchResource(self._client, "/search/expired")
+        self.nrds = SearchResource(self._client, "/search/nrds")
+        self.aged = SearchResource(self._client, "/search/aged")
+        self.active = SearchResource(self._client, "/search/active")
+        self.deleted = SearchResource(self._client, "/search/deleted")
+        self.market = SearchResource(self._client, "/search/market")
+
+    def usage(self) -> dict[str, Any]:
+        return self._client.request("/usage")
+
+    def search_status(self) -> dict[str, Any]:
+        return self._client.request("/search/status")
+
+    def health(self) -> dict[str, Any]:
+        return self._client.request_envelope("/health")
+
+    def whois(self, domain: str) -> dict[str, Any]:
+        return self._client.request("/whois", {"domain": domain})
+
+    def dns(self, domain: str) -> dict[str, Any]:
+        return self._client.request("/dns", {"domain": domain})
+
+    def safety(self, domain: str) -> dict[str, Any]:
+        return self._client.request("/safety", {"domain": domain})
+
+    def ip_lookup(self, query: str) -> dict[str, Any]:
+        return self._client.request("/ip-lookup", {"query": query})
+
+    def registrar(self, query: str) -> dict[str, Any]:
+        return self._client.request("/registrar", {"query": query})
+
+    def status_guide(self, query: str | None = None) -> dict[str, Any]:
+        return self._client.request("/status-guide", {"query": query})
+
+    def tld_check(self, prefix: str, **params: Any) -> dict[str, Any]:
+        return self._client.request_envelope("/tld-check", {"prefix": prefix, **params})
+
+    def ns_reverse(self, ns: str, **params: Any) -> dict[str, Any]:
+        return self._client.request_list("/ns-reverse", {"ns": ns, **params})
+
+    def typosquat(self, domain: str, **params: Any) -> dict[str, Any]:
+        return self._client.request_envelope("/typosquat", {"domain": domain, **params})
+
+    def monitor_changes(self, **params: Any) -> dict[str, Any]:
+        return self._client.request_list("/monitor/changes", params)
+
+    def ct_subdomains(self, domain: str, **params: Any) -> dict[str, Any]:
+        return self._client.request_list("/ct/subdomains", {"domain": domain, **params})
+
+    def ct_certs(self, **params: Any) -> dict[str, Any]:
+        return self._client.request_list("/ct/certs", params)
+
+    def ct_search(self, keyword: str, **params: Any) -> dict[str, Any]:
+        return self._client.request_list("/ct/search", {"keyword": keyword, **params})
+
+    def tld_trends(self, type: str, **params: Any) -> Any:
+        return self._client.request(f"/trends/tlds/{type}", params)
+
+    def keyword_trends(self, type: str, **params: Any) -> Any:
+        return self._client.request(f"/trends/keywords/{type}", params)
+
+    def nrds_download(self, **params: Any) -> bytes:
+        _, _, body = self._client.request_raw("/nrds/download", params)
+        return body

domainkits-0.1.0/domainkits/client.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any
+
+DEFAULT_BASE_URL = "https://premium-api.domainkits.com/api/v1"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_MAX_RETRIES = 2
+
+
+@dataclass
+class RateLimit:
+    limit: int | None
+    remaining: int | None
+    reset_at: datetime | None
+
+
+class DomainKitsError(Exception):
+    def __init__(self, message: str, status: int, rate_limit: RateLimit):
+        super().__init__(message)
+        self.status = status
+        self.rate_limit = rate_limit
+
+
+class RateLimitError(DomainKitsError):
+    def __init__(self, message: str, rate_limit: RateLimit):
+        super().__init__(message, 429, rate_limit)
+
+    @property
+    def retry_after_ms(self) -> int | None:
+        if not self.rate_limit.reset_at:
+            return None
+        delta = (self.rate_limit.reset_at - datetime.now(timezone.utc)).total_seconds() * 1000
+        return max(0, int(delta))
+
+
+class AuthError(DomainKitsError):
+    pass
+
+
+def _read_rate_limit(headers: Any) -> RateLimit:
+    def num(name: str) -> int | None:
+        raw = headers.get(name)
+        if raw is None:
+            return None
+        try:
+            return int(raw)
+        except ValueError:
+            return None
+
+    reset = num("x-ratelimit-reset")
+    return RateLimit(
+        limit=num("x-ratelimit-limit"),
+        remaining=num("x-ratelimit-remaining"),
+        reset_at=datetime.fromtimestamp(reset, tz=timezone.utc) if reset is not None else None,
+    )
+
+
+def _extract_error(body: bytes) -> str | None:
+    try:
+        parsed = json.loads(body)
+    except (ValueError, UnicodeDecodeError):
+        return None
+    error = parsed.get("error") if isinstance(parsed, dict) else None
+    return error if isinstance(error, str) else None
+
+
+def _backoff_seconds(error: RateLimitError, attempt: int) -> float | None:
+    until_ms = error.retry_after_ms
+    if until_ms is None:
+        return float(2**attempt)
+    if until_ms > 120_000:
+        return None
+    return until_ms / 1000 + 0.25
+
+
+class DomainKitsClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required. The DomainKits REST API rejects unauthenticated requests.")
+        self.api_key = api_key
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+    def request_raw(self, path: str, params: dict[str, Any] | None = None) -> tuple[int, Any, bytes]:
+        query: dict[str, str] = {}
+        for key, value in (params or {}).items():
+            if value is None or value == "":
+                continue
+            if isinstance(value, bool):
+                query[key] = "true" if value else "false"
+            elif isinstance(value, (list, tuple)):
+                query[key] = ",".join(str(v) for v in value)
+            else:
+                query[key] = str(value)
+        url = self.base_url + path
+        if query:
+            url += "?" + urllib.parse.urlencode(query)
+
+        last_error: DomainKitsError | None = None
+        for attempt in range(self.max_retries + 1):
+            request = urllib.request.Request(
+                url,
+                headers={
+                    "Authorization": f"Bearer {self.api_key}",
+                    "Accept": "application/json",
+                    "User-Agent": "domainkits-python/0.1.0",
+                },
+            )
+            try:
+                response = urllib.request.urlopen(request, timeout=self.timeout)
+                return response.status, response.headers, response.read()
+            except urllib.error.HTTPError as e:
+                body = e.read()
+                rate_limit = _read_rate_limit(e.headers)
+                message = _extract_error(body) or f"Request failed with status {e.code}"
+
+                if e.code in (401, 403):
+                    raise AuthError(message, e.code, rate_limit) from None
+
+                if e.code == 429:
+                    rate_error = RateLimitError(message, rate_limit)
+                    last_error = rate_error
+                    wait = _backoff_seconds(rate_error, attempt)
+                    if attempt < self.max_retries and wait is not None:
+                        time.sleep(wait)
+                        continue
+                    raise rate_error from None
+
+                if e.code >= 500 and attempt < self.max_retries:
+                    last_error = DomainKitsError(message, e.code, rate_limit)
+                    time.sleep(0.5 * (2**attempt))
+                    continue
+
+                raise DomainKitsError(message, e.code, rate_limit) from None
+
+        raise last_error if last_error else DomainKitsError(
+            "Request failed after retries", 0, RateLimit(None, None, None)
+        )
+
+    def _parse(self, path: str, params: dict[str, Any] | None) -> tuple[Any, int, Any]:
+        status, headers, body = self.request_raw(path, params)
+        envelope = json.loads(body)
+        if isinstance(envelope, dict) and envelope.get("success") is False:
+            raise DomainKitsError(
+                envelope.get("error") or "DomainKits API returned an error",
+                status,
+                _read_rate_limit(headers),
+            )
+        return envelope, status, headers
+
+    def request(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        envelope, _, _ = self._parse(path, params)
+        if isinstance(envelope, dict) and envelope.get("data") is not None:
+            return envelope["data"]
+        return envelope
+
+    def request_list(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        envelope, _, _ = self._parse(path, params)
+        data = envelope.get("data") if isinstance(envelope, dict) else None
+        if not isinstance(data, list):
+            data = []
+        total = envelope.get("total") if isinstance(envelope, dict) else None
+        return {"data": data, "total": total if isinstance(total, int) else len(data)}
+
+    def request_envelope(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        envelope, _, _ = self._parse(path, params)
+        return envelope

domainkits-0.1.0/domainkits.egg-info/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: domainkits
+Version: 0.1.0
+Summary: Python client for the DomainKits REST API. Search expiring, newly registered, aged, active, deleted and marketplace domains, plus WHOIS, DNS, Certificate Transparency and trends.
+Author-email: DomainKits <info@domainkits.com>
+License-Expression: MIT
+Project-URL: Homepage, https://domainkits.com/dev
+Project-URL: Documentation, https://domainkits.com/dev/api-docs
+Project-URL: Repository, https://github.com/ABTdomain/domainkits-sdk-py
+Keywords: domain,domain-search,expired-domains,newly-registered-domains,whois,dns,certificate-transparency,domainkits
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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 :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# domainkits
+
+Python client for the [DomainKits](https://domainkits.com) REST API.
+
+DomainKits is one API with a shared key across every endpoint. This package covers all of them, six domain search types, WHOIS, DNS, reverse nameserver, Certificate Transparency, safety, trends and bulk download, with automatic paging and structured quota errors. No dependencies.
+
+## Requirements
+
+The REST API is for Premium and Platinum accounts; unauthenticated requests are rejected with 401. Keys start with `dk_` and come from [domainkits.com](https://domainkits.com/pricing).
+
+## Install
+
+```bash
+pip install domainkits
+```
+
+## Usage
+
+```python
+import os
+from domainkits import DomainKits
+
+dk = DomainKits(os.environ["DOMAINKITS_API_KEY"])
+
+result = dk.expired.list(
+    keyword="clinic",
+    tld="com",
+    length="5-10",
+    no_number=True,
+    no_hyphen=True,
+)
+
+print(f"{result['total']} matches")
+for d in result["data"]:
+    print(d["domain"], d["age"], d["status"])
+```
+
+### Paging
+
+A single request returns at most 500 results. `paginate` walks the whole result set for you:
+
+```python
+for domain in dk.expired.paginate(keyword="clinic", tld="com"):
+    print(domain["domain"])
+```
+
+It stops when the result set is exhausted. Break out of the loop whenever you have enough; no further requests are made.
+
+### Export
+
+`export` pulls up to 50,000 rows as CSV in one request:
+
+```python
+csv = dk.expired.export(tld="com", status="pending_delete")
+```
+
+This runs on a separate, much smaller quota, 10 per day and 100 per month on Premium, 3 and 9 during the trial. It is for occasional bulk pulls, not for a scheduled job. The export also returns fewer columns than paged mode: `registered_date` is the year only, and `age` is omitted.
+
+50,000 is a cap, not a promise of completeness. Browsing `.com` matched 4,847,613 expiring domains on 27 July 2026, so an unfiltered export returns the first 50,000. Narrow the query if you need the result set to fit.
+
+## Search types
+
+| Attribute | What it searches |
+|---|---|
+| `dk.expired` | Domains in the deletion cycle: expired, redemption, pending delete |
+| `dk.nrds` | Newly registered domains, last 60 days |
+| `dk.aged` | Domains with 5 to 20+ years of registration history |
+| `dk.active` | Currently registered domains |
+| `dk.deleted` | Dropped domains (requires `keyword`) |
+| `dk.market` | Domains listed for sale on marketplaces |
+
+Each has `list`, `paginate` and `export`. Filters are passed as keyword arguments and match the REST parameter names: an expired result carries `status`, an NRD result carries `expiry_date`, a market result carries `marketplace`.
+
+## Other endpoints
+
+```python
+dk.whois("example.com")
+dk.dns("example.com")
+dk.safety("example.com")
+dk.ns_reverse("ns1.example.com", tld="com")
+dk.tld_check("yourbrand")
+dk.typosquat("example.com")
+dk.ip_lookup("8.8.8.8")
+dk.registrar("godaddy")
+dk.status_guide("clientHold")
+dk.monitor_changes(tld="com", reason="transfer")
+dk.ct_subdomains("example.com")
+dk.ct_certs(domain="example.com")
+dk.ct_search("example")
+dk.tld_trends("newly", tld="com")
+dk.keyword_trends("hot")
+dk.usage()
+dk.search_status()
+```
+
+## Coverage
+
+**gTLDs only** for the domain search endpoints. The index covers generic TLDs: `.com`, `.net`, `.org`, `.info`, `.biz`, `.xyz`, `.online`, `.site`, `.top`, `.club`, `.live`, `.app`, `.dev` and others. Country-code TLDs are not indexed: a query for `.de`, `.io`, `.co` or `.us` returns an empty result set, not an error.
+
+`whois`, `dns`, `safety`, `ip_lookup` and the Certificate Transparency endpoints work on any domain, ccTLDs included.
+
+**No PII.** Responses contain no personal data. WHOIS results are limited to registrar, dates, status codes and nameservers; registrant names, emails, addresses and phone numbers are not returned.
+
+## Errors
+
+```python
+from domainkits import DomainKits, DomainKitsError, RateLimitError, AuthError
+
+try:
+    dk.expired.export(tld="com")
+except RateLimitError as error:
+    print(f"Quota exhausted. Retry in {error.retry_after_ms}ms")
+    print(error.rate_limit)
+except AuthError:
+    print("Key rejected, check your plan tier")
+except DomainKitsError as error:
+    print(error.status, error)
+```
+
+Every error carries the `x-ratelimit-limit`, `x-ratelimit-remaining` and `x-ratelimit-reset` values as a parsed `rate_limit` object. `RateLimitError.retry_after_ms` tells you how long until the window resets.
+
+429 and 5xx responses are retried automatically, twice by default, waiting until the rate-limit window resets when that is under two minutes. Set `max_retries=0` to handle it yourself.
+
+## Options
+
+```python
+dk = DomainKits(
+    api_key=os.environ["DOMAINKITS_API_KEY"],
+    timeout=60.0,
+    max_retries=2,
+    base_url="https://premium-api.domainkits.com/api/v1",
+)
+```
+
+## Quotas
+
+Call `usage()` for the live picture on your account; every endpoint reports its own per-minute, daily and monthly allowance alongside what you have already spent.
+
+Daily quotas reset at 00:00 UTC, monthly quotas on the 1st. Current limits: [domainkits.com/dev/api-docs](https://domainkits.com/dev/api-docs).
+
+## Resources
+
+- [DomainKits API reference](https://domainkits.com/dev/api-docs)
+- [@domainkits/sdk](https://www.npmjs.com/package/@domainkits/sdk), the same API for TypeScript
+- [n8n-nodes-domainkits](https://www.npmjs.com/package/n8n-nodes-domainkits), the same API for n8n
+
+## License
+
+MIT

domainkits-0.1.0/domainkits.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+domainkits/__init__.py
+domainkits/client.py
+domainkits.egg-info/PKG-INFO
+domainkits.egg-info/SOURCES.txt
+domainkits.egg-info/dependency_links.txt
+domainkits.egg-info/top_level.txt

domainkits-0.1.0/domainkits.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

domainkits-0.1.0/domainkits.egg-info/top_level.txt

@@ -0,0 +1 @@
+domainkits

domainkits-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "domainkits"
+version = "0.1.0"
+description = "Python client for the DomainKits REST API. Search expiring, newly registered, aged, active, deleted and marketplace domains, plus WHOIS, DNS, Certificate Transparency and trends."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "DomainKits", email = "info@domainkits.com"}
+]
+keywords = ["domain", "domain-search", "expired-domains", "newly-registered-domains", "whois", "dns", "certificate-transparency", "domainkits"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "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 :: Internet :: WWW/HTTP",
+]
+requires-python = ">=3.9"
+dependencies = []
+
+[project.urls]
+Homepage = "https://domainkits.com/dev"
+Documentation = "https://domainkits.com/dev/api-docs"
+Repository = "https://github.com/ABTdomain/domainkits-sdk-py"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["domainkits*"]

domainkits-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+