dokaz-api 0.1.0__tar.gz

dokaz_api-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/

dokaz_api-0.1.0/LICENSE

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

dokaz_api-0.1.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.5
+Name: dokaz-api
+Version: 0.1.0
+Summary: Official client for the Dokaz API: invoice PDFs, QR codes, barcodes, Markdown to PDF, CSV/JSON/Excel, calendar .ics files, image metadata removal, email verification, site intel and text AI.
+Project-URL: Homepage, https://api.dokaz.net
+Project-URL: Documentation, https://api.dokaz.net/docs
+Project-URL: Pricing, https://api.dokaz.net/#pricing
+Project-URL: OpenAPI, https://api.dokaz.net/openapi.json
+Author: Dokaz Industries
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,barcode,csv,dokaz,email-verification,exif,ics,invoice,markdown,pdf,qr-code,xlsx
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# dokaz-api
+
+The official Python client for the [Dokaz API](https://api.dokaz.net): invoice PDFs, Markdown to
+PDF, QR codes and barcodes, CSV/JSON/Excel conversion, calendar (.ics) files, photo metadata
+removal, email verification, website intel and text AI, all from one key.
+
+- Standard library only (urllib). No dependencies.
+- Python 3.9+, fully typed (`py.typed`, TypedDicts for requests and responses).
+- One method per API endpoint. PDFs, PNGs, JPEGs and spreadsheets come back as `bytes`; SVG, CSV
+  and iCalendar as `str`; everything else as parsed JSON.
+
+```sh
+pip install dokaz-api
+```
+
+```python
+from dokaz_api import Dokaz
+```
+
+## Free tier and plans
+
+**100 calls a day are free with no key and no signup.** Just call it. For more, get a key at
+**[api.dokaz.net/#pricing](https://api.dokaz.net/#pricing)**: Starter $9/month (10,000 calls),
+Pro $29/month (100,000), Business $79/month (500,000). Every plan covers every endpoint. The key
+is shown straight after checkout.
+
+```python
+dokaz = Dokaz()               # uses DOKAZ_API_KEY if set, else the free tier
+dokaz = Dokaz("dk_...")       # or pass the key
+```
+
+## Quick start
+
+### Invoice PDF
+
+```python
+pdf = dokaz.invoice_pdf({
+    "number": "INV-2026-0142",
+    "date": "2026-09-06",
+    "due": "2026-10-06",
+    "from": {"name": "Northwind Studio LLC", "address": ["1200 Market Street", "San Francisco, CA 94102"]},
+    "to": {"name": "Acme Robotics Inc.", "email": "ap@acme-robotics.example"},
+    "items": [
+        {"description": "Brand identity design", "qty": 1, "unit_price": 2400},
+        {"description": "Front-end implementation (hourly)", "qty": 32, "unit_price": 110},
+    ],
+    "tax_rate": 8.25,
+})
+open("invoice.pdf", "wb").write(pdf)
+
+totals = dokaz.invoice_preview(same_body)   # {"subtotal", "tax", "total", "line_items", ...}
+```
+
+### Markdown to PDF
+
+```python
+pdf = dokaz.pdf_markdown("# 2.4\n\n- Faster **exports**", title="Release notes", page_size="a4")
+```
+
+### QR codes and barcodes
+
+```python
+svg = dokaz.qr("https://example.com", size=256, ec="Q")        # str
+png = dokaz.qr("https://example.com", format="png")            # bytes
+wifi = dokaz.qr_wifi("Cafe Guest", password="latte123", format="png")
+card = dokaz.qr_vcard("Ada Lovelace", email="ada@example.com")
+ean = dokaz.barcode("400638133393", type="ean13", text=True)    # SVG str
+```
+
+### CSV, JSON and Excel
+
+```python
+rows = dokaz.convert_csv_to_json('name,city\n"Hopper, Grace",Arlington')   # [{"name": ..., "city": ...}]
+csv = dokaz.convert_json_to_csv([{"name": "Ada", "born": 1815}])           # RFC 4180 text
+xlsx = dokaz.convert_json_to_xlsx({"rows": [{"order": "A-1001", "total": 129.5}], "sheet_name": "Orders"})
+```
+
+### Calendar (.ics) files
+
+```python
+ics = dokaz.calendar_ics_post({
+    "title": "Kitchen remodel consult",
+    "start": "2026-10-05T14:00:00-07:00",
+    "end": "2026-10-05T15:00:00-07:00",
+    "reminder_minutes": 60,
+})
+# An "Add to calendar" link for an email, with no request made and no key in it:
+link = dokaz.calendar_ics_link("Webinar", "2026-10-08T17:00:00Z")
+```
+
+### Strip photo metadata (EXIF, GPS, XMP)
+
+```python
+clean = dokaz.image_strip(open("photo.jpg", "rb").read())   # same pixels, no metadata
+no_icc = dokaz.image_strip(data, keep_icc=False)
+```
+
+### Email verification and website intel
+
+```python
+r = dokaz.email_verify("sales@gmial.com")        # r["valid"], r["score"], r["checks"]["typo_suggestion"]
+batch = dokaz.email_verify_batch(["a@example.org", "b@mailinator.com"])   # up to 50, one call
+site = dokaz.site_intel("https://example.com")    # title, OpenGraph, tech, contacts, socials
+```
+
+### Text AI
+
+```python
+dokaz.text_summarize(text, sentences=2, style="bullets")
+dokaz.text_sentiment(text)
+dokaz.text_keywords(text, max=10)
+dokaz.text_classify(text, ["billing", "bug report", "other"])
+dokaz.text_extract(text, ["name", "company", "phone"])
+dokaz.text_rewrite(text, "professional")
+```
+
+## Errors
+
+Every non-2xx response raises `DokazError` carrying the API's error body:
+
+```python
+from dokaz_api import DokazError
+
+try:
+    dokaz.invoice_pdf(body)
+except DokazError as e:
+    e.status        # 400, 401, 404, 413, 429, 503 ...
+    e.error         # the API's message (e.body is the whole JSON)
+    e.errors        # every validation problem, when listed
+    e.upgrade       # on 429: where to upgrade
+    e.retry_after   # on 503 (text AI capacity): seconds to wait
+```
+
+A request that gets no response at all (DNS, connection, timeout) raises `DokazConnectionError`,
+a `DokazError` with `status` 0.
+
+## Quota, options and raw responses
+
+```python
+dokaz = Dokaz(
+    "dk_...",              # default: DOKAZ_API_KEY; None forces the anonymous free tier
+    timeout=30,            # seconds, default 60
+    on_response=lambda i: print(i.operation, i.status, i.quota),   # Quota(plan, limit, used)
+)
+
+# Any call with its status and headers (x-pdf-pages, x-csv-rows, x-metadata-removed ...):
+r = dokaz.request("pdf_markdown", json={"markdown": "# Hi"})
+r.headers["x-pdf-pages"], r.data
+```
+
+## Methods
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `invoice_pdf(invoice)` | `POST /v1/invoice/pdf` | `bytes` (PDF) |
+| `invoice_preview(invoice)` | `POST /v1/invoice/preview` | totals |
+| `invoice_sample()` | `GET /v1/invoice/sample` | `bytes` (PDF) |
+| `email_verify(email)` | `GET /v1/email/verify` | result |
+| `email_verify_post(email)` | `POST /v1/email/verify` | result |
+| `email_verify_batch(emails)` | `POST /v1/email/verify/batch` | `{"count", "results"}` |
+| `site_intel(url)` | `GET /v1/site/intel` | dict |
+| `site_intel_post(url)` | `POST /v1/site/intel` | dict |
+| `text_summarize` `text_sentiment` `text_keywords` `text_classify` `text_extract` `text_rewrite` | `POST /v1/text/*` | dict |
+| `qr(data, ...)` / `qr_post(data, ...)` | `GET` / `POST /v1/qr` | SVG `str`, PNG `bytes` or matrix |
+| `qr_wifi(ssid, ...)` | `GET /v1/qr/wifi` | as `qr` |
+| `qr_vcard(name, ...)` | `GET /v1/qr/vcard` | as `qr` |
+| `barcode(data, ...)` | `GET /v1/barcode` | SVG `str` |
+| `pdf_markdown(markdown, ...)` | `POST /v1/pdf/markdown` | `bytes` (PDF) |
+| `convert_csv_to_json(csv, ...)` | `POST /v1/convert/csv-to-json` | rows |
+| `convert_json_to_csv(rows, ...)` | `POST /v1/convert/json-to-csv` | CSV `str` |
+| `convert_json_to_xlsx(body)` | `POST /v1/convert/json-to-xlsx` | `bytes` (.xlsx) |
+| `calendar_ics(title, start, ...)` | `GET /v1/calendar/ics` | iCalendar `str` |
+| `calendar_ics_post(event)` | `POST /v1/calendar/ics` | iCalendar `str` |
+| `image_strip(data, ...)` | `POST /v1/image/strip` | `bytes` (image) |
+
+Field names are the API's own, so the guides at [api.dokaz.net/docs](https://api.dokaz.net/docs)
+and the [OpenAPI document](https://api.dokaz.net/openapi.json) apply unchanged.
+
+## License
+
+MIT

dokaz_api-0.1.0/README.md

@@ -0,0 +1,181 @@
+# dokaz-api
+
+The official Python client for the [Dokaz API](https://api.dokaz.net): invoice PDFs, Markdown to
+PDF, QR codes and barcodes, CSV/JSON/Excel conversion, calendar (.ics) files, photo metadata
+removal, email verification, website intel and text AI, all from one key.
+
+- Standard library only (urllib). No dependencies.
+- Python 3.9+, fully typed (`py.typed`, TypedDicts for requests and responses).
+- One method per API endpoint. PDFs, PNGs, JPEGs and spreadsheets come back as `bytes`; SVG, CSV
+  and iCalendar as `str`; everything else as parsed JSON.
+
+```sh
+pip install dokaz-api
+```
+
+```python
+from dokaz_api import Dokaz
+```
+
+## Free tier and plans
+
+**100 calls a day are free with no key and no signup.** Just call it. For more, get a key at
+**[api.dokaz.net/#pricing](https://api.dokaz.net/#pricing)**: Starter $9/month (10,000 calls),
+Pro $29/month (100,000), Business $79/month (500,000). Every plan covers every endpoint. The key
+is shown straight after checkout.
+
+```python
+dokaz = Dokaz()               # uses DOKAZ_API_KEY if set, else the free tier
+dokaz = Dokaz("dk_...")       # or pass the key
+```
+
+## Quick start
+
+### Invoice PDF
+
+```python
+pdf = dokaz.invoice_pdf({
+    "number": "INV-2026-0142",
+    "date": "2026-09-06",
+    "due": "2026-10-06",
+    "from": {"name": "Northwind Studio LLC", "address": ["1200 Market Street", "San Francisco, CA 94102"]},
+    "to": {"name": "Acme Robotics Inc.", "email": "ap@acme-robotics.example"},
+    "items": [
+        {"description": "Brand identity design", "qty": 1, "unit_price": 2400},
+        {"description": "Front-end implementation (hourly)", "qty": 32, "unit_price": 110},
+    ],
+    "tax_rate": 8.25,
+})
+open("invoice.pdf", "wb").write(pdf)
+
+totals = dokaz.invoice_preview(same_body)   # {"subtotal", "tax", "total", "line_items", ...}
+```
+
+### Markdown to PDF
+
+```python
+pdf = dokaz.pdf_markdown("# 2.4\n\n- Faster **exports**", title="Release notes", page_size="a4")
+```
+
+### QR codes and barcodes
+
+```python
+svg = dokaz.qr("https://example.com", size=256, ec="Q")        # str
+png = dokaz.qr("https://example.com", format="png")            # bytes
+wifi = dokaz.qr_wifi("Cafe Guest", password="latte123", format="png")
+card = dokaz.qr_vcard("Ada Lovelace", email="ada@example.com")
+ean = dokaz.barcode("400638133393", type="ean13", text=True)    # SVG str
+```
+
+### CSV, JSON and Excel
+
+```python
+rows = dokaz.convert_csv_to_json('name,city\n"Hopper, Grace",Arlington')   # [{"name": ..., "city": ...}]
+csv = dokaz.convert_json_to_csv([{"name": "Ada", "born": 1815}])           # RFC 4180 text
+xlsx = dokaz.convert_json_to_xlsx({"rows": [{"order": "A-1001", "total": 129.5}], "sheet_name": "Orders"})
+```
+
+### Calendar (.ics) files
+
+```python
+ics = dokaz.calendar_ics_post({
+    "title": "Kitchen remodel consult",
+    "start": "2026-10-05T14:00:00-07:00",
+    "end": "2026-10-05T15:00:00-07:00",
+    "reminder_minutes": 60,
+})
+# An "Add to calendar" link for an email, with no request made and no key in it:
+link = dokaz.calendar_ics_link("Webinar", "2026-10-08T17:00:00Z")
+```
+
+### Strip photo metadata (EXIF, GPS, XMP)
+
+```python
+clean = dokaz.image_strip(open("photo.jpg", "rb").read())   # same pixels, no metadata
+no_icc = dokaz.image_strip(data, keep_icc=False)
+```
+
+### Email verification and website intel
+
+```python
+r = dokaz.email_verify("sales@gmial.com")        # r["valid"], r["score"], r["checks"]["typo_suggestion"]
+batch = dokaz.email_verify_batch(["a@example.org", "b@mailinator.com"])   # up to 50, one call
+site = dokaz.site_intel("https://example.com")    # title, OpenGraph, tech, contacts, socials
+```
+
+### Text AI
+
+```python
+dokaz.text_summarize(text, sentences=2, style="bullets")
+dokaz.text_sentiment(text)
+dokaz.text_keywords(text, max=10)
+dokaz.text_classify(text, ["billing", "bug report", "other"])
+dokaz.text_extract(text, ["name", "company", "phone"])
+dokaz.text_rewrite(text, "professional")
+```
+
+## Errors
+
+Every non-2xx response raises `DokazError` carrying the API's error body:
+
+```python
+from dokaz_api import DokazError
+
+try:
+    dokaz.invoice_pdf(body)
+except DokazError as e:
+    e.status        # 400, 401, 404, 413, 429, 503 ...
+    e.error         # the API's message (e.body is the whole JSON)
+    e.errors        # every validation problem, when listed
+    e.upgrade       # on 429: where to upgrade
+    e.retry_after   # on 503 (text AI capacity): seconds to wait
+```
+
+A request that gets no response at all (DNS, connection, timeout) raises `DokazConnectionError`,
+a `DokazError` with `status` 0.
+
+## Quota, options and raw responses
+
+```python
+dokaz = Dokaz(
+    "dk_...",              # default: DOKAZ_API_KEY; None forces the anonymous free tier
+    timeout=30,            # seconds, default 60
+    on_response=lambda i: print(i.operation, i.status, i.quota),   # Quota(plan, limit, used)
+)
+
+# Any call with its status and headers (x-pdf-pages, x-csv-rows, x-metadata-removed ...):
+r = dokaz.request("pdf_markdown", json={"markdown": "# Hi"})
+r.headers["x-pdf-pages"], r.data
+```
+
+## Methods
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `invoice_pdf(invoice)` | `POST /v1/invoice/pdf` | `bytes` (PDF) |
+| `invoice_preview(invoice)` | `POST /v1/invoice/preview` | totals |
+| `invoice_sample()` | `GET /v1/invoice/sample` | `bytes` (PDF) |
+| `email_verify(email)` | `GET /v1/email/verify` | result |
+| `email_verify_post(email)` | `POST /v1/email/verify` | result |
+| `email_verify_batch(emails)` | `POST /v1/email/verify/batch` | `{"count", "results"}` |
+| `site_intel(url)` | `GET /v1/site/intel` | dict |
+| `site_intel_post(url)` | `POST /v1/site/intel` | dict |
+| `text_summarize` `text_sentiment` `text_keywords` `text_classify` `text_extract` `text_rewrite` | `POST /v1/text/*` | dict |
+| `qr(data, ...)` / `qr_post(data, ...)` | `GET` / `POST /v1/qr` | SVG `str`, PNG `bytes` or matrix |
+| `qr_wifi(ssid, ...)` | `GET /v1/qr/wifi` | as `qr` |
+| `qr_vcard(name, ...)` | `GET /v1/qr/vcard` | as `qr` |
+| `barcode(data, ...)` | `GET /v1/barcode` | SVG `str` |
+| `pdf_markdown(markdown, ...)` | `POST /v1/pdf/markdown` | `bytes` (PDF) |
+| `convert_csv_to_json(csv, ...)` | `POST /v1/convert/csv-to-json` | rows |
+| `convert_json_to_csv(rows, ...)` | `POST /v1/convert/json-to-csv` | CSV `str` |
+| `convert_json_to_xlsx(body)` | `POST /v1/convert/json-to-xlsx` | `bytes` (.xlsx) |
+| `calendar_ics(title, start, ...)` | `GET /v1/calendar/ics` | iCalendar `str` |
+| `calendar_ics_post(event)` | `POST /v1/calendar/ics` | iCalendar `str` |
+| `image_strip(data, ...)` | `POST /v1/image/strip` | `bytes` (image) |
+
+Field names are the API's own, so the guides at [api.dokaz.net/docs](https://api.dokaz.net/docs)
+and the [OpenAPI document](https://api.dokaz.net/openapi.json) apply unchanged.
+
+## License
+
+MIT

dokaz_api-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dokaz-api"
+version = "0.1.0"
+description = "Official client for the Dokaz API: invoice PDFs, QR codes, barcodes, Markdown to PDF, CSV/JSON/Excel, calendar .ics files, image metadata removal, email verification, site intel and text AI."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Dokaz Industries" }]
+keywords = ["dokaz", "api", "invoice", "pdf", "markdown", "qr-code", "barcode", "csv", "xlsx", "ics", "exif", "email-verification"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "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",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://api.dokaz.net"
+Documentation = "https://api.dokaz.net/docs"
+Pricing = "https://api.dokaz.net/#pricing"
+"OpenAPI" = "https://api.dokaz.net/openapi.json"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dokaz_api"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/dokaz_api", "README.md", "LICENSE", "pyproject.toml"]

dokaz_api-0.1.0/src/dokaz_api/__init__.py

@@ -0,0 +1,33 @@
+"""Official Python client for the Dokaz API (https://api.dokaz.net).
+
+    from dokaz_api import Dokaz
+    dokaz = Dokaz()            # DOKAZ_API_KEY if set, else the free tier (100 calls/day, no key)
+    pdf = dokaz.pdf_markdown("# Hello")
+"""
+
+from ._client import (
+    DEFAULT_BASE_URL,
+    OPERATIONS,
+    PRICING_URL,
+    Dokaz,
+    DokazResponse,
+    Quota,
+    ResponseInfo,
+    __version__,
+    read_quota,
+)
+from ._errors import DokazConnectionError, DokazError
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "OPERATIONS",
+    "PRICING_URL",
+    "Dokaz",
+    "DokazConnectionError",
+    "DokazError",
+    "DokazResponse",
+    "Quota",
+    "ResponseInfo",
+    "__version__",
+    "read_quota",
+]

dokaz_api-0.1.0/src/dokaz_api/_client.py

@@ -0,0 +1,462 @@
+# mypy: disable-error-code="no-any-return"
+"""The Dokaz API client. Standard library only (urllib)."""
+
+from __future__ import annotations
+
+import json as _json
+import os
+import re
+import socket
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from email.message import Message
+from typing import Any, Callable, Dict, Generic, List, Literal, Mapping, Optional, Tuple, TypeVar, Union, overload
+
+from ._errors import DokazConnectionError, DokazError
+from .types import (
+    BarcodeType,
+    CalendarRequest,
+    ClassifyResult,
+    EcLevel,
+    EmailBatchResult,
+    EmailResult,
+    ExtractResult,
+    InvoiceRequest,
+    InvoiceTotals,
+    KeywordsResult,
+    QrMatrix,
+    QrResult,
+    Rows,
+    RewriteResult,
+    SentimentResult,
+    SiteIntel,
+    SummarizeResult,
+    Tone,
+    XlsxRequest,
+)
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://api.dokaz.net"
+PRICING_URL = "https://api.dokaz.net/#pricing"
+
+#: Every API operation this client implements: method name -> (HTTP method, path). The drift test
+#: checks this table against the API's OpenAPI document, so an endpoint added to the API fails the
+#: test until it gets a method here. Naming: the path after /v1 in snake_case, plus "_post" for the
+#: POST form of a path that also has a GET.
+OPERATIONS: Dict[str, Tuple[str, str]] = {
+    "invoice_pdf": ("POST", "/v1/invoice/pdf"),
+    "invoice_preview": ("POST", "/v1/invoice/preview"),
+    "invoice_sample": ("GET", "/v1/invoice/sample"),
+    "email_verify": ("GET", "/v1/email/verify"),
+    "email_verify_post": ("POST", "/v1/email/verify"),
+    "email_verify_batch": ("POST", "/v1/email/verify/batch"),
+    "site_intel": ("GET", "/v1/site/intel"),
+    "site_intel_post": ("POST", "/v1/site/intel"),
+    "text_summarize": ("POST", "/v1/text/summarize"),
+    "text_sentiment": ("POST", "/v1/text/sentiment"),
+    "text_keywords": ("POST", "/v1/text/keywords"),
+    "text_classify": ("POST", "/v1/text/classify"),
+    "text_extract": ("POST", "/v1/text/extract"),
+    "text_rewrite": ("POST", "/v1/text/rewrite"),
+    "qr": ("GET", "/v1/qr"),
+    "qr_post": ("POST", "/v1/qr"),
+    "qr_wifi": ("GET", "/v1/qr/wifi"),
+    "qr_vcard": ("GET", "/v1/qr/vcard"),
+    "barcode": ("GET", "/v1/barcode"),
+    "pdf_markdown": ("POST", "/v1/pdf/markdown"),
+    "convert_csv_to_json": ("POST", "/v1/convert/csv-to-json"),
+    "convert_json_to_csv": ("POST", "/v1/convert/json-to-csv"),
+    "convert_json_to_xlsx": ("POST", "/v1/convert/json-to-xlsx"),
+    "calendar_ics": ("GET", "/v1/calendar/ics"),
+    "calendar_ics_post": ("POST", "/v1/calendar/ics"),
+    "image_strip": ("POST", "/v1/image/strip"),
+}
+
+T = TypeVar("T")
+Query = Mapping[str, Union[str, int, float, bool, None]]
+
+
+@dataclass(frozen=True)
+class Quota:
+    """The plan and usage headers every /v1 response carries."""
+
+    #: free | starter | pro | business | rapid:<plan>
+    plan: Optional[str]
+    #: Calls allowed in the window (per day on free, per month on paid); "rapidapi" via RapidAPI.
+    limit: Optional[str]
+    used: Optional[int]
+
+
+def read_quota(headers: Message) -> Quota:
+    used = headers.get("x-quota-used")
+    return Quota(plan=headers.get("x-plan"), limit=headers.get("x-quota-limit"), used=int(used) if used and used.isdigit() else None)
+
+
+@dataclass(frozen=True)
+class ResponseInfo:
+    operation: str
+    status: int
+    headers: Message
+    quota: Quota
+
+
+@dataclass(frozen=True)
+class DokazResponse(Generic[T]):
+    """A decoded response: the value plus the status and (case-insensitive) headers."""
+
+    data: T
+    status: int
+    headers: Message
+
+
+class _Unset:
+    def __repr__(self) -> str:
+        return "<from DOKAZ_API_KEY>"
+
+
+_UNSET = _Unset()
+_JSON_TYPE = re.compile(r"^application/(?:[\w.+-]+\+)?json\b", re.I)
+_TEXT_TYPE = re.compile(r"^(?:text/|image/svg\+xml\b)", re.I)
+
+
+def _env(name: str) -> Optional[str]:
+    v = os.environ.get(name)
+    return v if v else None
+
+
+def _query_string(q: Optional[Query]) -> str:
+    if not q:
+        return ""
+    pairs = []
+    for k, v in q.items():
+        if v is None:
+            continue
+        if isinstance(v, bool):
+            v = "1" if v else "0"
+        pairs.append((k, str(v)))
+    return "?" + urllib.parse.urlencode(pairs) if pairs else ""
+
+
+def _sniff_image(data: bytes) -> str:
+    if data[:4] == b"\x89PNG":
+        return "image/png"
+    if data[:2] == b"\xff\xd8":
+        return "image/jpeg"
+    return "application/octet-stream"
+
+
+def _drop_none(d: Mapping[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+class Dokaz:
+    """Client for https://api.dokaz.net.
+
+    ``api_key``: your key (dk_...). Default: the DOKAZ_API_KEY environment variable when set.
+    Pass ``None`` (or "") to call the free tier anonymously: 100 calls a day per IP, no key.
+    """
+
+    def __init__(
+        self,
+        api_key: Union[str, None, _Unset] = _UNSET,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        on_response: Optional[Callable[[ResponseInfo], None]] = None,
+    ) -> None:
+        key = _env("DOKAZ_API_KEY") if isinstance(api_key, _Unset) else api_key
+        self.__api_key: Optional[str] = key or None
+        self.base_url: str = (base_url or _env("DOKAZ_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.on_response = on_response
+
+    @property
+    def has_api_key(self) -> bool:
+        return self.__api_key is not None
+
+    def __repr__(self) -> str:
+        return f"Dokaz({self.base_url!r}, {'key' if self.__api_key else 'anonymous'})"
+
+    # ------------------------------------------------------------------ transport
+
+    def request(
+        self,
+        operation: str,
+        *,
+        query: Optional[Query] = None,
+        json: Any = None,
+        body: Optional[bytes] = None,
+        content_type: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> DokazResponse[Any]:
+        """Low-level call: any operation, returning the decoded body with its status and headers.
+
+        JSON responses are parsed, text (SVG, CSV, iCalendar) is ``str``, anything else ``bytes``.
+        """
+        if operation not in OPERATIONS:
+            raise ValueError(f"dokaz: unknown operation {operation!r}")
+        method, path = OPERATIONS[operation]
+        url = self.base_url + path + _query_string(query)
+        headers = {"Accept": "*/*", "User-Agent": f"dokaz-api-python/{__version__}"}
+        if self.__api_key:
+            headers["X-Api-Key"] = self.__api_key
+        data: Optional[bytes] = None
+        if json is not None:
+            data = _json.dumps(json).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        elif body is not None:
+            data = bytes(body)
+            headers["Content-Type"] = content_type or "application/octet-stream"
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        limit = self.timeout if timeout is None else timeout
+
+        try:
+            with urllib.request.urlopen(req, timeout=limit) as res:  # noqa: S310 - https URL built above
+                status, resp_headers, raw = res.status, res.headers, res.read()
+        except urllib.error.HTTPError as e:
+            status, resp_headers = e.code, e.headers
+            try:
+                raw = e.read()
+            except Exception:  # pragma: no cover - a body cut off mid-read
+                raw = b""
+        except (socket.timeout, TimeoutError) as e:
+            raise DokazConnectionError(f"dokaz: {method} {path} failed: timed out after {limit} s", operation) from e
+        except (urllib.error.URLError, OSError) as e:
+            reason = getattr(e, "reason", e)
+            raise DokazConnectionError(f"dokaz: {method} {path} failed: {reason}", operation) from e
+
+        if self.on_response is not None:
+            self.on_response(ResponseInfo(operation, status, resp_headers, read_quota(resp_headers)))
+        ctype = resp_headers.get("content-type") or ""
+
+        if status >= 400:
+            text = raw.decode("utf-8", "replace")
+            try:
+                parsed = _json.loads(text)
+                err_body = parsed if isinstance(parsed, dict) and isinstance(parsed.get("error"), str) else {"error": text[:500]}
+            except ValueError:
+                err_body = {"error": text[:500] or f"HTTP {status}"}
+            raise DokazError(f"dokaz: {method} {path} -> {status}: {err_body['error']}", status, err_body, resp_headers, operation)
+
+        value: Any
+        if _JSON_TYPE.match(ctype):
+            value = _json.loads(raw.decode("utf-8"))
+        elif _TEXT_TYPE.match(ctype):
+            value = raw.decode("utf-8")
+        else:
+            value = raw
+        return DokazResponse(value, status, resp_headers)
+
+    def _call(self, operation: str, **kw: Any) -> Any:
+        return self.request(operation, **kw).data
+
+    # ------------------------------------------------------------------ Invoice PDF
+
+    def invoice_pdf(self, invoice: InvoiceRequest) -> bytes:
+        """Render an invoice, estimate or receipt as PDF bytes."""
+        return self._call("invoice_pdf", json=invoice)
+
+    def invoice_preview(self, invoice: InvoiceRequest) -> InvoiceTotals:
+        """The computed totals and per-line amounts, to check the math before rendering."""
+        return self._call("invoice_preview", json=invoice)
+
+    def invoice_sample(self) -> bytes:
+        """A sample invoice PDF rendered from built-in demo data."""
+        return self._call("invoice_sample")
+
+    # ------------------------------------------------------------------ Email Verify
+
+    def email_verify(self, email: str) -> EmailResult:
+        """Verify one address: syntax, MX, disposable, role account, typo suggestion; score 0-100."""
+        return self._call("email_verify", query={"email": email})
+
+    def email_verify_post(self, email: str) -> EmailResult:
+        """Same as email_verify, sent as a JSON body (keeps the address out of URLs and logs)."""
+        return self._call("email_verify_post", json={"email": email})
+
+    def email_verify_batch(self, emails: List[str]) -> EmailBatchResult:
+        """Verify up to 50 addresses in one call; results in request order."""
+        return self._call("email_verify_batch", json={"emails": list(emails)})
+
+    # ------------------------------------------------------------------ Site Intel
+
+    def site_intel(self, url: str) -> SiteIntel:
+        """Title/meta/OpenGraph, tech stack, contacts, socials and more for a public web page."""
+        return self._call("site_intel", query={"url": url})
+
+    def site_intel_post(self, url: str) -> SiteIntel:
+        """Same as site_intel, as a JSON body; a scheme-less "example.com" is treated as https."""
+        return self._call("site_intel_post", json={"url": url})
+
+    # ------------------------------------------------------------------ Text AI
+
+    def text_summarize(self, text: str, *, sentences: Optional[int] = None, style: Optional[Literal["paragraph", "bullets"]] = None) -> SummarizeResult:
+        return self._call("text_summarize", json=_drop_none({"text": text, "sentences": sentences, "style": style}))
+
+    def text_sentiment(self, text: str) -> SentimentResult:
+        return self._call("text_sentiment", json={"text": text})
+
+    def text_keywords(self, text: str, *, max: Optional[int] = None) -> KeywordsResult:  # noqa: A002 - the API's name
+        return self._call("text_keywords", json=_drop_none({"text": text, "max": max}))
+
+    def text_classify(self, text: str, labels: List[str]) -> ClassifyResult:
+        return self._call("text_classify", json={"text": text, "labels": list(labels)})
+
+    def text_extract(self, text: str, fields: List[str]) -> ExtractResult:
+        return self._call("text_extract", json={"text": text, "fields": list(fields)})
+
+    def text_rewrite(self, text: str, tone: Tone) -> RewriteResult:
+        return self._call("text_rewrite", json={"text": text, "tone": tone})
+
+    # ------------------------------------------------------------------ QR codes
+    # format "svg" (default) returns str, "png" bytes, "json" the module matrix.
+
+    @overload
+    def qr(self, data: str, *, format: Literal["png"], size: Optional[int] = ..., margin: Optional[int] = ..., ec: Optional[EcLevel] = ..., fg: Optional[str] = ..., bg: Optional[str] = ..., rounded: Optional[bool] = ...) -> bytes: ...
+    @overload
+    def qr(self, data: str, *, format: Literal["json"], size: Optional[int] = ..., margin: Optional[int] = ..., ec: Optional[EcLevel] = ..., fg: Optional[str] = ..., bg: Optional[str] = ..., rounded: Optional[bool] = ...) -> QrMatrix: ...
+    @overload
+    def qr(self, data: str, *, format: Optional[Literal["svg"]] = ..., size: Optional[int] = ..., margin: Optional[int] = ..., ec: Optional[EcLevel] = ..., fg: Optional[str] = ..., bg: Optional[str] = ..., rounded: Optional[bool] = ...) -> str: ...
+    def qr(self, data: str, *, format: Optional[str] = None, size: Optional[int] = None, margin: Optional[int] = None, ec: Optional[str] = None, fg: Optional[str] = None, bg: Optional[str] = None, rounded: Optional[bool] = None) -> QrResult:
+        """A QR code for any text or URL (up to 2953 bytes)."""
+        return self._call("qr", query=dict(data=data, format=format, size=size, margin=margin, ec=ec, fg=fg, bg=bg, rounded=rounded))
+
+    @overload
+    def qr_post(self, data: str, *, format: Literal["png"], size: Optional[int] = ..., margin: Optional[int] = ..., ec: Optional[EcLevel] = ..., fg: Optional[str] = ..., bg: Optional[str] = ..., rounded: Optional[bool] = ...) -> bytes: ...
+    @overload
+    def qr_post(self, data: str, *, format: Literal["json"], size: Optional[int] = ..., margin: Optional[int] = ..., ec: Optional[EcLevel] = ..., fg: Optional[str] = ..., bg: Optional[str] = ..., rounded: Optional[bool] = ...) -> QrMatrix: ...
+    @overload
+    def qr_post(self, data: str, *, format: Optional[Literal["svg"]] = ..., size: Optional[int] = ..., margin: Optional[int] = ..., ec: Optional[EcLevel] = ..., fg: Optional[str] = ..., bg: Optional[str] = ..., rounded: Optional[bool] = ...) -> str: ...
+    def qr_post(self, data: str, *, format: Optional[str] = None, size: Optional[int] = None, margin: Optional[int] = None, ec: Optional[str] = None, fg: Optional[str] = None, bg: Optional[str] = None, rounded: Optional[bool] = None) -> QrResult:
+        """Same as qr, sent as a JSON body."""
+        return self._call("qr_post", json=_drop_none(dict(data=data, format=format, size=size, margin=margin, ec=ec, fg=fg, bg=bg, rounded=rounded)))
+
+    @overload
+    def qr_wifi(self, ssid: str, *, password: Optional[str] = ..., type: Optional[Literal["WPA", "WEP", "nopass"]] = ..., hidden: Optional[bool] = ..., format: Literal["png"], size: Optional[int] = ..., margin: Optional[int] = ..., ec: Optional[EcLevel] = ..., fg: Optional[str] = ..., bg: Optional[str] = ..., rounded: Optional[bool] = ...) -> bytes: ...
+    @overload
+    def qr_wifi(self, ssid: str, *, password: Optional[str] = ..., type: Optional[Literal["WPA", "WEP", "nopass"]] = ..., hidden: Optional[bool] = ..., format: Literal["json"], size: Optional[int] = ..., margin: Optional[int] = ..., ec: Optional[EcLevel] = ..., fg: Optional[str] = ..., bg: Optional[str] = ..., rounded: Optional[bool] = ...) -> QrMatrix: ...
+    @overload
+    def qr_wifi(self, ssid: str, *, password: Optional[str] = ..., type: Optional[Literal["WPA", "WEP", "nopass"]] = ..., hidden: Optional[bool] = ..., format: Optional[Literal["svg"]] = ..., size: Optional[int] = ..., margin: Optional[int] = ..., ec: Optional[EcLevel] = ..., fg: Optional[str] = ..., bg: Optional[str] = ..., rounded: Optional[bool] = ...) -> str: ...
+    def qr_wifi(self, ssid: str, *, password: Optional[str] = None, type: Optional[str] = None, hidden: Optional[bool] = None, format: Optional[str] = None, size: Optional[int] = None, margin: Optional[int] = None, ec: Optional[str] = None, fg: Optional[str] = None, bg: Optional[str] = None, rounded: Optional[bool] = None) -> QrResult:  # noqa: A002
+        """A QR code that joins a Wi-Fi network when scanned."""
+        q = dict(ssid=ssid, password=password, type=type, hidden=hidden, format=format, size=size, margin=margin, ec=ec, fg=fg, bg=bg, rounded=rounded)
+        return self._call("qr_wifi", query=q)
+
+    @overload
+    def qr_vcard(self, name: str, *, phone: Optional[str] = ..., email: Optional[str] = ..., org: Optional[str] = ..., url: Optional[str] = ..., format: Literal["png"], size: Optional[int] = ..., margin: Optional[int] = ..., ec: Optional[EcLevel] = ..., fg: Optional[str] = ..., bg: Optional[str] = ..., rounded: Optional[bool] = ...) -> bytes: ...
+    @overload
+    def qr_vcard(self, name: str, *, phone: Optional[str] = ..., email: Optional[str] = ..., org: Optional[str] = ..., url: Optional[str] = ..., format: Literal["json"], size: Optional[int] = ..., margin: Optional[int] = ..., ec: Optional[EcLevel] = ..., fg: Optional[str] = ..., bg: Optional[str] = ..., rounded: Optional[bool] = ...) -> QrMatrix: ...
+    @overload
+    def qr_vcard(self, name: str, *, phone: Optional[str] = ..., email: Optional[str] = ..., org: Optional[str] = ..., url: Optional[str] = ..., format: Optional[Literal["svg"]] = ..., size: Optional[int] = ..., margin: Optional[int] = ..., ec: Optional[EcLevel] = ..., fg: Optional[str] = ..., bg: Optional[str] = ..., rounded: Optional[bool] = ...) -> str: ...
+    def qr_vcard(self, name: str, *, phone: Optional[str] = None, email: Optional[str] = None, org: Optional[str] = None, url: Optional[str] = None, format: Optional[str] = None, size: Optional[int] = None, margin: Optional[int] = None, ec: Optional[str] = None, fg: Optional[str] = None, bg: Optional[str] = None, rounded: Optional[bool] = None) -> QrResult:
+        """A QR code holding a vCard 3.0 contact."""
+        q = dict(name=name, phone=phone, email=email, org=org, url=url, format=format, size=size, margin=margin, ec=ec, fg=fg, bg=bg, rounded=rounded)
+        return self._call("qr_vcard", query=q)
+
+    # ------------------------------------------------------------------ Barcodes
+
+    def barcode(
+        self,
+        data: str,
+        *,
+        type: Optional[BarcodeType] = None,  # noqa: A002 - the API's name
+        text: Optional[bool] = None,
+        scale: Optional[int] = None,
+        height: Optional[int] = None,
+        margin: Optional[int] = None,
+        fg: Optional[str] = None,
+        bg: Optional[str] = None,
+    ) -> str:
+        """A Code 128 (default), EAN-13 or UPC-A barcode as SVG text."""
+        q = dict(data=data, type=type, text=text, scale=scale, height=height, margin=margin, fg=fg, bg=bg)
+        return self._call("barcode", query=q)
+
+    # ------------------------------------------------------------------ Markdown to PDF
+
+    def pdf_markdown(self, markdown: str, *, title: Optional[str] = None, page_size: Optional[Literal["letter", "a4"]] = None) -> bytes:
+        """Render Markdown as PDF bytes."""
+        return self._call("pdf_markdown", json=_drop_none({"markdown": markdown, "title": title, "page_size": page_size}))
+
+    # ------------------------------------------------------------------ CSV / JSON / Excel
+
+    def convert_csv_to_json(self, csv: str, *, delimiter: Optional[str] = None, header: Optional[bool] = None) -> List[Any]:
+        """CSV text to rows: dicts keyed by the header (default), or lists when header=False."""
+        return self._call("convert_csv_to_json", json=_drop_none({"csv": csv, "delimiter": delimiter, "header": header}))
+
+    def convert_json_to_csv(self, rows: Rows, *, delimiter: Optional[str] = None, header: Optional[bool] = None) -> str:
+        """Rows (dicts, or lists) to RFC 4180 CSV text."""
+        return self._call("convert_json_to_csv", json=_drop_none({"rows": rows, "delimiter": delimiter, "header": header}))
+
+    def convert_json_to_xlsx(self, body: XlsxRequest) -> bytes:
+        """Rows, {"rows", "sheet_name"}, or {"sheets": [...]} to an Excel workbook (.xlsx bytes)."""
+        return self._call("convert_json_to_xlsx", json=body)
+
+    # ------------------------------------------------------------------ Calendar (.ics)
+
+    def calendar_ics(
+        self,
+        title: str,
+        start: str,
+        *,
+        end: Optional[str] = None,
+        description: Optional[str] = None,
+        location: Optional[str] = None,
+        url: Optional[str] = None,
+        uid: Optional[str] = None,
+        status: Optional[Literal["confirmed", "tentative", "cancelled"]] = None,
+        reminder_minutes: Optional[int] = None,
+    ) -> str:
+        """One event from query parameters, as iCalendar text."""
+        return self._call("calendar_ics", query=self._ics_query(title, start, end, description, location, url, uid, status, reminder_minutes))
+
+    def calendar_ics_post(self, event: CalendarRequest) -> str:
+        """One event, or {"name", "events": [...]} with organizer, attendees and repeats, as iCalendar text."""
+        return self._call("calendar_ics_post", json=event)
+
+    def calendar_ics_link(
+        self,
+        title: str,
+        start: str,
+        *,
+        end: Optional[str] = None,
+        description: Optional[str] = None,
+        location: Optional[str] = None,
+        url: Optional[str] = None,
+        uid: Optional[str] = None,
+        status: Optional[Literal["confirmed", "tentative", "cancelled"]] = None,
+        reminder_minutes: Optional[int] = None,
+    ) -> str:
+        """An "Add to calendar" link (the GET form of calendar_ics) for an email or a page.
+
+        Makes no request and never includes your key: whoever clicks it uses their own free call.
+        """
+        q = self._ics_query(title, start, end, description, location, url, uid, status, reminder_minutes)
+        return self.base_url + OPERATIONS["calendar_ics"][1] + _query_string(q)
+
+    @staticmethod
+    def _ics_query(*values: Any) -> Dict[str, Any]:
+        keys = ("title", "start", "end", "description", "location", "url", "uid", "status", "reminder_minutes")
+        return dict(zip(keys, values))
+
+    # ------------------------------------------------------------------ Image metadata
+
+    def image_strip(self, image: bytes, *, keep_icc: Optional[bool] = None, keep_orientation: Optional[bool] = None) -> bytes:
+        """A JPEG or PNG with EXIF/GPS/XMP/IPTC/comments removed; the pixels are untouched."""
+        data = bytes(image)
+        q = {"keep_icc": keep_icc, "keep_orientation": keep_orientation}
+        return self._call("image_strip", query=q, body=data, content_type=_sniff_image(data))
+
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "Dokaz",
+    "DokazResponse",
+    "OPERATIONS",
+    "PRICING_URL",
+    "Quota",
+    "ResponseInfo",
+    "read_quota",
+]

dokaz_api-0.1.0/src/dokaz_api/_errors.py

@@ -0,0 +1,51 @@
+"""Errors raised by the Dokaz client."""
+
+from __future__ import annotations
+
+from email.message import Message
+from typing import Any, Dict, List, Optional
+
+
+class DokazError(Exception):
+    """A non-2xx response. ``status`` is the HTTP status; ``body`` the API's error JSON.
+
+    The API's error body always has ``error`` (a message) and sometimes more: ``errors`` (every
+    validation problem), ``upgrade`` (on a 429, where to upgrade), ``retry_after`` (on a 503 from
+    the text AI endpoints, seconds to wait).
+    """
+
+    def __init__(self, message: str, status: int, body: Dict[str, Any], headers: Optional[Message], operation: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body
+        self.headers = headers
+        self.operation = operation
+
+    @property
+    def error(self) -> str:
+        return str(self.body.get("error", ""))
+
+    @property
+    def errors(self) -> Optional[List[str]]:
+        v = self.body.get("errors")
+        return v if isinstance(v, list) else None
+
+    @property
+    def retry_after(self) -> Optional[int]:
+        v = self.body.get("retry_after")
+        if isinstance(v, int):
+            return v
+        h = self.headers.get("retry-after") if self.headers is not None else None
+        return int(h) if h and h.isdigit() else None
+
+    @property
+    def upgrade(self) -> Optional[str]:
+        v = self.body.get("upgrade")
+        return v if isinstance(v, str) else None
+
+
+class DokazConnectionError(DokazError):
+    """The request got no HTTP response: DNS, connection, TLS or timeout. ``status`` is 0."""
+
+    def __init__(self, message: str, operation: str) -> None:
+        super().__init__(message, 0, {"error": message}, None, operation)

dokaz_api-0.1.0/src/dokaz_api/types.py

@@ -0,0 +1,239 @@
+"""Request and response types for the Dokaz API.
+
+Field names are exactly the API's (snake_case), so the endpoint docs at
+https://api.dokaz.net/docs apply to these dicts unchanged. Every TypedDict here is
+``total=False`` (Python 3.9 has no ``Required``); the docstrings say which keys the API requires.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, TypedDict, Union
+
+# ---------------------------------------------------------------- invoice
+
+
+class InvoiceParty(TypedDict, total=False):
+    """``name`` is required. ``address``: up to 5 lines, a list or one newline-separated string."""
+
+    name: str
+    address: Union[List[str], str]
+    email: str
+    phone: str
+
+
+class InvoiceItem(TypedDict, total=False):
+    """``description``, ``qty`` and ``unit_price`` are required."""
+
+    description: str
+    qty: float
+    unit_price: float
+    tax_rate: float
+
+
+InvoiceRequest = TypedDict(
+    "InvoiceRequest",
+    {
+        "kind": Literal["invoice", "estimate", "receipt"],
+        "number": str,
+        "date": str,
+        "due": str,
+        "currency": Literal["USD", "EUR", "GBP", "CAD", "AUD"],
+        "from": InvoiceParty,
+        "to": InvoiceParty,
+        "items": List[InvoiceItem],
+        "tax_rate": float,
+        "discount": float,
+        "notes": str,
+        "terms": str,
+        "paid": bool,
+        "logo_text": str,
+    },
+    total=False,
+)
+"""Required: number, date (YYYY-MM-DD), from, to, items (1..60)."""
+
+
+class InvoiceLineTotal(TypedDict):
+    description: str
+    qty: float
+    unit_price: float
+    tax_rate: float
+    amount: float
+    tax: float
+
+
+class InvoiceTotals(TypedDict):
+    subtotal: float
+    tax: float
+    discount: float
+    total: float
+    currency: str
+    line_items: List[InvoiceLineTotal]
+
+
+# ---------------------------------------------------------------- email
+
+
+class EmailChecks(TypedDict):
+    syntax: bool
+    domain_has_mx: Optional[bool]
+    mx_hosts: List[str]
+    disposable: bool
+    role_account: bool
+    free_provider: bool
+    typo_suggestion: Optional[str]
+    gibberish_local: bool
+
+
+class EmailResult(TypedDict):
+    email: str
+    normalized: str
+    valid: bool
+    score: int
+    checks: EmailChecks
+    reason: str
+
+
+class EmailBatchResult(TypedDict):
+    count: int
+    results: List[EmailResult]
+
+
+# ---------------------------------------------------------------- site
+
+SiteIntel = Dict[str, Any]
+"""url, final_url, status, redirect_chain, title, description, og, tech, contacts, socials, ..."""
+
+# ---------------------------------------------------------------- text AI
+
+
+class SummarizeResult(TypedDict, total=False):
+    summary: str
+    sentences: int
+    input_chars: int
+    model: str
+    fallback_reason: str
+
+
+class SentimentResult(TypedDict, total=False):
+    label: str
+    score: float
+    confidence: float
+    model: str
+    fallback_reason: str
+
+
+class Keyword(TypedDict):
+    term: str
+    weight: float
+
+
+class KeywordsResult(TypedDict, total=False):
+    keywords: List[Keyword]
+    model: str
+    fallback_reason: str
+
+
+class ClassifyResult(TypedDict, total=False):
+    label: str
+    scores: Dict[str, float]
+    model: str
+    fallback_reason: str
+
+
+class ExtractResult(TypedDict, total=False):
+    data: Dict[str, Any]
+    model: str
+    fallback_reason: str
+
+
+class RewriteResult(TypedDict, total=False):
+    text: str
+    model: str
+    fallback_reason: str
+
+
+Tone = Literal["professional", "casual", "concise", "friendly", "formal"]
+
+# ---------------------------------------------------------------- QR and barcode
+
+QrFormat = Literal["svg", "png", "json"]
+EcLevel = Literal["L", "M", "Q", "H"]
+
+
+class QrMatrix(TypedDict):
+    """format="json": the raw module matrix, one string of 1/0 per row."""
+
+    version: int
+    ec: str
+    mode: str
+    mask: int
+    modules: int
+    matrix: List[str]
+
+
+QrResult = Union[str, bytes, QrMatrix]
+BarcodeType = Literal["code128", "ean13", "upca"]
+
+# ---------------------------------------------------------------- convert
+
+Row = Dict[str, Any]
+Rows = Union[List[Row], List[List[Any]]]
+
+
+class XlsxSheet(TypedDict, total=False):
+    """``name`` and ``rows`` are required."""
+
+    name: str
+    rows: Rows
+    header: bool
+
+
+XlsxRequest = Union[Rows, Dict[str, Any]]
+"""Rows; or {"rows": ..., "sheet_name"?: ..., "header"?: ...}; or {"sheets": [XlsxSheet, ...]}."""
+
+# ---------------------------------------------------------------- calendar
+
+
+class CalendarPerson(TypedDict, total=False):
+    """``email`` is required."""
+
+    name: str
+    email: str
+
+
+class CalendarRepeat(TypedDict, total=False):
+    """``freq`` is required."""
+
+    freq: Literal["daily", "weekly", "monthly", "yearly"]
+    interval: int
+    count: int
+    until: str
+    by_day: List[Literal["MO", "TU", "WE", "TH", "FR", "SA", "SU"]]
+
+
+class CalendarEvent(TypedDict, total=False):
+    """``title`` and ``start`` are required. start: "2026-10-05T14:00:00-07:00" or "2026-10-05"."""
+
+    title: str
+    start: str
+    end: str
+    description: str
+    location: str
+    url: str
+    uid: str
+    status: Literal["confirmed", "tentative", "cancelled"]
+    reminder_minutes: int
+    organizer: CalendarPerson
+    attendees: List[CalendarPerson]
+    repeat: CalendarRepeat
+
+
+class CalendarFile(TypedDict, total=False):
+    """Several events in one file. ``events`` (1..100) is required."""
+
+    name: str
+    events: List[CalendarEvent]
+
+
+CalendarRequest = Union[CalendarEvent, CalendarFile]