honkio 0.1.0__tar.gz

honkio-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv*/
+dist/
+__pycache__/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

honkio-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+Versions are published to PyPI by hand; a version without a date is not on PyPI yet.
+
+## 0.1.0
+
+First release, with the coverage of `@honkio/node` 0.7.0.
+
+### Added
+
+- `Honkio` and `AsyncHonkio` clients over httpx, with the same resources and arguments: messages, phone numbers, verify, consents, consent batches, opt-in confirmations, webhooks, emails (and `emails.received`), batch, domains, suppressions, templates, toll-free verifications, business verification, auto top-up and top-up cap requests.
+- Errors are exceptions: `ApiError` and a subclass per status, `APIConnectionError`, `APITimeoutError`, `InvalidArgumentError`, `InvalidSignatureError`.
+- `verify_webhook` (also `client.webhooks.verify`) and `WEBHOOK_EVENTS`.
+- `TypedDict` response types generated from the OpenAPI snapshot, and `py.typed`.
+- `ENDPOINTS`: every route the SDK calls.
+- `NOT_GIVEN`: optional arguments default to it and are not sent; `None` is sent as JSON `null` in a body.

honkio-0.1.0/LICENSE

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

honkio-0.1.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.5
+Name: honkio
+Version: 0.1.0
+Summary: Official Python SDK for HonkIO: Canadian SMS and email, CASL built in.
+Project-URL: Homepage, https://honkio.ca/docs/sdk
+Project-URL: Documentation, https://honkio.ca/docs/sdk
+Project-URL: Issues, https://honkio.ca/contact
+Author: somethingcorporate
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,canada,casl,email,honkio,sms
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# honkio
+
+The official Python SDK for [HonkIO](https://honkio.ca): Canadian SMS and email, with CASL built in. Data is stored in Canada (ca-central-1).
+
+- Python 3.10 or newer; one dependency, [httpx](https://www.python-httpx.org)
+- A synchronous client (`Honkio`) and an asynchronous one (`AsyncHonkio`) with the same resources and arguments
+- Errors are exceptions; every API error is a subclass of `honkio.ApiError`
+- Typed (`py.typed`); responses are plain dicts described by `TypedDict`s, importable from `honkio.types` (`from honkio.types import Message`)
+- No automatic retries: a send costs money, so retrying is your call (use an idempotency key)
+
+## Install
+
+```sh
+pip install honkio
+```
+
+## Quickstart
+
+Create a key in the dashboard under API Keys, Create key (<https://honkio.ca/dashboard/keys>); the full key is shown once, right after you create it. Start with a test key (`mk_test_...`): nothing is delivered or charged.
+
+Send an SMS:
+
+```python
+from honkio import Honkio
+
+client = Honkio()  # reads HONKIO_API_KEY
+
+message = client.messages.send(
+    from_="+1416XXXXXXX",  # one of your HonkIO numbers
+    to="+1613XXXXXXX",  # a Canadian number you hold consent for
+    body="Hello from HonkIO!",
+    idempotency_key="order-1042",
+)
+print(message["id"], message["status"])
+```
+
+Send an email:
+
+```python
+sent = client.emails.send(
+    from_="Acme <hello@yourdomain.ca>",  # a verified sending domain
+    to="sam@example.com",
+    subject="Welcome",
+    html="<p>Hello!</p>",
+    idempotency_key="welcome-sam",
+)
+print(sent["id"])
+```
+
+The same calls, asynchronously:
+
+```python
+import asyncio
+from honkio import AsyncHonkio
+
+
+async def main() -> None:
+    async with AsyncHonkio() as client:
+        message = await client.messages.send(from_="+1416XXXXXXX", to="+1613XXXXXXX", body="Hi")
+        print(message["id"])
+
+
+asyncio.run(main())
+```
+
+`Honkio()` with no argument reads `HONKIO_API_KEY` and raises `InvalidArgumentError` if neither is set. Options: `Honkio(api_key, base_url="https://api.honkio.ca", timeout=30.0, http_client=None)`. Pass your own `httpx.Client` (or `httpx.AsyncClient`) as `http_client` for proxies, mTLS or tests; the SDK then leaves closing it to you, and the timeout is the one you configured on it (`timeout=` applies only to a client the SDK builds). A client the SDK built is closed by `client.close()` (`await client.aclose()`), or by leaving a `with` (`async with`) block.
+
+## Arguments
+
+Every call takes keyword-only arguments named like the API's own (snake_case) fields. `from` is a Python keyword, so it is `from_` and is sent as `from`. A typo is a `TypeError`, not a silently ignored field. Ids come first, positionally: `client.domains.remove("dom_1")`.
+
+An optional argument you leave out is not sent (its default is `honkio.NOT_GIVEN`). Pass `None` to send an explicit JSON `null`, which clears a nullable field: `client.domains.update("dom_1", open_tracking=None)` restores the platform default, `client.templates.update("welcome", html=None)` removes the HTML. In a query string `None` is omitted like `NOT_GIVEN`. Dicts you pass (`variables`, `headers`, template objects) are sent exactly as you wrote them. Query lists repeat the key.
+
+Datetimes: pass a timezone-aware `datetime` (or an ISO 8601 string). It is sent in UTC with a `Z` suffix, so `datetime(2026, 10, 15, 9, 0, tzinfo=ZoneInfo("America/Toronto"))` goes out as `2026-10-15T13:00:00Z`. A naive `datetime` raises `InvalidArgumentError` before anything is sent. The two date-only filters of `messages.list` (`date_from`, `date_to`) and `last_transaction_date` on consents take a `date` or a `YYYY-MM-DD` string and are sent as `YYYY-MM-DD` (a timezone-aware `datetime` there is converted to its UTC date).
+
+## Errors
+
+```python
+from honkio import ApiError, UnavailableForLegalReasonsError, UnprocessableEntityError, APITimeoutError
+
+try:
+    client.messages.send(from_="+1416XXXXXXX", to="+1613XXXXXXX", body="Hi")
+except UnavailableForLegalReasonsError as e:  # HTTP 451
+    print(e.code, e.message)  # NO_CONSENT, CONSENT_EXPIRED, OPT_OUT_BLOCKED
+except UnprocessableEntityError as e:  # HTTP 422
+    print(e.code, e.message)  # NON_CANADIAN_NUMBER, ...
+except ApiError as e:
+    print(e.status_code, e.code, e.details)
+except APITimeoutError:
+    ...  # the send may or may not have gone through: retry with the same idempotency key
+```
+
+| Exception | When |
+|---|---|
+| `ApiError` (`.code`, `.message`, `.status_code`, `.details`) | the API answered with an error; subclasses by status: `BadRequestError` 400, `AuthenticationError` 401, `PaymentRequiredError` 402, `PermissionDeniedError` 403, `NotFoundError` 404, `ConflictError` 409, `UnprocessableEntityError` 422, `RateLimitError` 429, `UnavailableForLegalReasonsError` 451, `InternalServerError` 5xx |
+| `APIConnectionError`, `APITimeoutError` | no response arrived (DNS, refused connection, 30 s timeout) |
+| `InvalidArgumentError` (also a `ValueError`) | refused before anything was sent: an id that is empty, `.` or `..`, a consent call that named both or neither subject, a naive `datetime`, an empty `api_key`, a webhook check with a missing secret |
+| `InvalidSignatureError` | a webhook delivery could not be verified |
+| `HonkioError` | the base of all of the above |
+
+Every `ApiError` pickles (for task queues and multiprocessing). A 3xx answer (the SDK does not follow redirects) is an `ApiError` whose message and `details["location"]` carry the `Location` header; check `base_url`.
+
+`details` is the API's `details` when it sent one. Otherwise it holds whatever the API sent beside the error envelope, such as `{"attempts_remaining": 2}` on `VERIFICATION_INVALID_CODE`. A body that is not JSON (a proxy error page, say) is `ApiError` with code `application_error`.
+
+The general codes (authentication, permissions, balance, validation, rate limits) and every SMS and email code are listed at <https://honkio.ca/docs/errors>.
+
+## Idempotency
+
+`messages.send`, `emails.send` and `batch.send` take `idempotency_key=`, sent as the `Idempotency-Key` header. Reuse the key when you retry, and a send can never go out or be charged twice.
+
+## Webhooks
+
+Check a delivery's signature before you trust it. Pass the raw request body exactly as received, before any JSON parsing:
+
+```python
+from honkio import verify_webhook, InvalidSignatureError
+
+
+def handle(request):  # a Flask-style request
+    try:
+        event = verify_webhook(request.get_data(), request.headers, WEBHOOK_SECRET)
+    except InvalidSignatureError:
+        return "bad signature", 400
+    if event["type"] == "message.delivered":
+        ...
+    return "", 204
+```
+
+`verify_webhook(raw_body, headers, secret, *, tolerance_seconds=300)` takes a `str` or `bytes` body and any mapping of headers, or any object with `.items()` such as Flask/Werkzeug `request.headers` (names are matched case-insensitively; a list value uses its first item; a list of tuples is refused with `InvalidArgumentError`). It returns the parsed event, raises `InvalidSignatureError` for anything about the signature, the timestamp (more than 300 seconds old) or the body, and `InvalidArgumentError` for bad input such as a body already parsed into a dict. `client.webhooks.verify(...)` is the same function. On `AsyncHonkio` it is still a plain function, not awaitable: call it without `await`. `honkio.WEBHOOK_EVENTS` lists every event a webhook can subscribe to.
+
+## Resources
+
+| `client.` | Methods |
+|---|---|
+| `messages` | `send`, `get`, `list` |
+| `phone_numbers` | `area_codes`, `search`, `provision`, `list`, `get`, `release` |
+| `verify` | `start`, `check`, `get`, `list` |
+| `consents` | `create`, `list`, `record_batch`, `check`, `revoke` (the last two take exactly one of `phone_number` or `email_address`) |
+| `consent_batches` | `list`, `get` |
+| `opt_in_confirmations` | `send`, `list` |
+| `webhooks` | `create`, `list`, `get`, `update`, `remove`, `deliveries`, `dead_letters`, `replay`, `discard`, `reactivate`, `rotate_secret`, `verify` |
+| `emails` | `send`, `get`, `list`, `update`, `cancel` |
+| `emails.received` | `list`, `address`, `set_address_enabled`, `get`, `raw`, `attachment`, `simulate` |
+| `batch` | `send` (a list of emails, or `recipients=` for one message to many) |
+| `domains` | `create`, `get`, `list`, `update`, `verify`, `remove` |
+| `suppressions` | `create`, `list`, `remove` |
+| `templates` | `create`, `get`, `list`, `update`, `publish`, `rollback`, `versions`, `remove` |
+| `toll_free_verifications` | `options`, `create`, `update`, `submit`, `cancel`, `get`, `list` |
+| `business_verification` | `get`, `save`, `submit` |
+| `auto_topup` | `get` |
+| `topup_cap_requests` | `create`, `list` |
+
+`emails.received.raw` and `emails.received.attachment` return `bytes`. A call that answers 204 (the deletes) returns `None`.
+
+Full API reference: <https://honkio.ca/docs/api>. SDK guide: <https://honkio.ca/docs/sdk>.
+
+## Development
+
+```sh
+uv venv && uv pip install -e '.[dev]'
+ruff check . && mypy --strict src && pytest
+python scripts/generate_types.py   # after web/generated/openapi.json changes
+```
+
+Inside the monorepo, the test suite reads `web/generated/openapi.json` (and the API source) and fails when a route or keyword argument the SDK uses is not in the spec, when `WEBHOOK_EVENTS` differs from the API's list, or when `src/honkio/_types.py` is stale. Those tests skip when run from a checkout without the monorepo.
+
+## License
+
+MIT

honkio-0.1.0/README.md

@@ -0,0 +1,169 @@
+# honkio
+
+The official Python SDK for [HonkIO](https://honkio.ca): Canadian SMS and email, with CASL built in. Data is stored in Canada (ca-central-1).
+
+- Python 3.10 or newer; one dependency, [httpx](https://www.python-httpx.org)
+- A synchronous client (`Honkio`) and an asynchronous one (`AsyncHonkio`) with the same resources and arguments
+- Errors are exceptions; every API error is a subclass of `honkio.ApiError`
+- Typed (`py.typed`); responses are plain dicts described by `TypedDict`s, importable from `honkio.types` (`from honkio.types import Message`)
+- No automatic retries: a send costs money, so retrying is your call (use an idempotency key)
+
+## Install
+
+```sh
+pip install honkio
+```
+
+## Quickstart
+
+Create a key in the dashboard under API Keys, Create key (<https://honkio.ca/dashboard/keys>); the full key is shown once, right after you create it. Start with a test key (`mk_test_...`): nothing is delivered or charged.
+
+Send an SMS:
+
+```python
+from honkio import Honkio
+
+client = Honkio()  # reads HONKIO_API_KEY
+
+message = client.messages.send(
+    from_="+1416XXXXXXX",  # one of your HonkIO numbers
+    to="+1613XXXXXXX",  # a Canadian number you hold consent for
+    body="Hello from HonkIO!",
+    idempotency_key="order-1042",
+)
+print(message["id"], message["status"])
+```
+
+Send an email:
+
+```python
+sent = client.emails.send(
+    from_="Acme <hello@yourdomain.ca>",  # a verified sending domain
+    to="sam@example.com",
+    subject="Welcome",
+    html="<p>Hello!</p>",
+    idempotency_key="welcome-sam",
+)
+print(sent["id"])
+```
+
+The same calls, asynchronously:
+
+```python
+import asyncio
+from honkio import AsyncHonkio
+
+
+async def main() -> None:
+    async with AsyncHonkio() as client:
+        message = await client.messages.send(from_="+1416XXXXXXX", to="+1613XXXXXXX", body="Hi")
+        print(message["id"])
+
+
+asyncio.run(main())
+```
+
+`Honkio()` with no argument reads `HONKIO_API_KEY` and raises `InvalidArgumentError` if neither is set. Options: `Honkio(api_key, base_url="https://api.honkio.ca", timeout=30.0, http_client=None)`. Pass your own `httpx.Client` (or `httpx.AsyncClient`) as `http_client` for proxies, mTLS or tests; the SDK then leaves closing it to you, and the timeout is the one you configured on it (`timeout=` applies only to a client the SDK builds). A client the SDK built is closed by `client.close()` (`await client.aclose()`), or by leaving a `with` (`async with`) block.
+
+## Arguments
+
+Every call takes keyword-only arguments named like the API's own (snake_case) fields. `from` is a Python keyword, so it is `from_` and is sent as `from`. A typo is a `TypeError`, not a silently ignored field. Ids come first, positionally: `client.domains.remove("dom_1")`.
+
+An optional argument you leave out is not sent (its default is `honkio.NOT_GIVEN`). Pass `None` to send an explicit JSON `null`, which clears a nullable field: `client.domains.update("dom_1", open_tracking=None)` restores the platform default, `client.templates.update("welcome", html=None)` removes the HTML. In a query string `None` is omitted like `NOT_GIVEN`. Dicts you pass (`variables`, `headers`, template objects) are sent exactly as you wrote them. Query lists repeat the key.
+
+Datetimes: pass a timezone-aware `datetime` (or an ISO 8601 string). It is sent in UTC with a `Z` suffix, so `datetime(2026, 10, 15, 9, 0, tzinfo=ZoneInfo("America/Toronto"))` goes out as `2026-10-15T13:00:00Z`. A naive `datetime` raises `InvalidArgumentError` before anything is sent. The two date-only filters of `messages.list` (`date_from`, `date_to`) and `last_transaction_date` on consents take a `date` or a `YYYY-MM-DD` string and are sent as `YYYY-MM-DD` (a timezone-aware `datetime` there is converted to its UTC date).
+
+## Errors
+
+```python
+from honkio import ApiError, UnavailableForLegalReasonsError, UnprocessableEntityError, APITimeoutError
+
+try:
+    client.messages.send(from_="+1416XXXXXXX", to="+1613XXXXXXX", body="Hi")
+except UnavailableForLegalReasonsError as e:  # HTTP 451
+    print(e.code, e.message)  # NO_CONSENT, CONSENT_EXPIRED, OPT_OUT_BLOCKED
+except UnprocessableEntityError as e:  # HTTP 422
+    print(e.code, e.message)  # NON_CANADIAN_NUMBER, ...
+except ApiError as e:
+    print(e.status_code, e.code, e.details)
+except APITimeoutError:
+    ...  # the send may or may not have gone through: retry with the same idempotency key
+```
+
+| Exception | When |
+|---|---|
+| `ApiError` (`.code`, `.message`, `.status_code`, `.details`) | the API answered with an error; subclasses by status: `BadRequestError` 400, `AuthenticationError` 401, `PaymentRequiredError` 402, `PermissionDeniedError` 403, `NotFoundError` 404, `ConflictError` 409, `UnprocessableEntityError` 422, `RateLimitError` 429, `UnavailableForLegalReasonsError` 451, `InternalServerError` 5xx |
+| `APIConnectionError`, `APITimeoutError` | no response arrived (DNS, refused connection, 30 s timeout) |
+| `InvalidArgumentError` (also a `ValueError`) | refused before anything was sent: an id that is empty, `.` or `..`, a consent call that named both or neither subject, a naive `datetime`, an empty `api_key`, a webhook check with a missing secret |
+| `InvalidSignatureError` | a webhook delivery could not be verified |
+| `HonkioError` | the base of all of the above |
+
+Every `ApiError` pickles (for task queues and multiprocessing). A 3xx answer (the SDK does not follow redirects) is an `ApiError` whose message and `details["location"]` carry the `Location` header; check `base_url`.
+
+`details` is the API's `details` when it sent one. Otherwise it holds whatever the API sent beside the error envelope, such as `{"attempts_remaining": 2}` on `VERIFICATION_INVALID_CODE`. A body that is not JSON (a proxy error page, say) is `ApiError` with code `application_error`.
+
+The general codes (authentication, permissions, balance, validation, rate limits) and every SMS and email code are listed at <https://honkio.ca/docs/errors>.
+
+## Idempotency
+
+`messages.send`, `emails.send` and `batch.send` take `idempotency_key=`, sent as the `Idempotency-Key` header. Reuse the key when you retry, and a send can never go out or be charged twice.
+
+## Webhooks
+
+Check a delivery's signature before you trust it. Pass the raw request body exactly as received, before any JSON parsing:
+
+```python
+from honkio import verify_webhook, InvalidSignatureError
+
+
+def handle(request):  # a Flask-style request
+    try:
+        event = verify_webhook(request.get_data(), request.headers, WEBHOOK_SECRET)
+    except InvalidSignatureError:
+        return "bad signature", 400
+    if event["type"] == "message.delivered":
+        ...
+    return "", 204
+```
+
+`verify_webhook(raw_body, headers, secret, *, tolerance_seconds=300)` takes a `str` or `bytes` body and any mapping of headers, or any object with `.items()` such as Flask/Werkzeug `request.headers` (names are matched case-insensitively; a list value uses its first item; a list of tuples is refused with `InvalidArgumentError`). It returns the parsed event, raises `InvalidSignatureError` for anything about the signature, the timestamp (more than 300 seconds old) or the body, and `InvalidArgumentError` for bad input such as a body already parsed into a dict. `client.webhooks.verify(...)` is the same function. On `AsyncHonkio` it is still a plain function, not awaitable: call it without `await`. `honkio.WEBHOOK_EVENTS` lists every event a webhook can subscribe to.
+
+## Resources
+
+| `client.` | Methods |
+|---|---|
+| `messages` | `send`, `get`, `list` |
+| `phone_numbers` | `area_codes`, `search`, `provision`, `list`, `get`, `release` |
+| `verify` | `start`, `check`, `get`, `list` |
+| `consents` | `create`, `list`, `record_batch`, `check`, `revoke` (the last two take exactly one of `phone_number` or `email_address`) |
+| `consent_batches` | `list`, `get` |
+| `opt_in_confirmations` | `send`, `list` |
+| `webhooks` | `create`, `list`, `get`, `update`, `remove`, `deliveries`, `dead_letters`, `replay`, `discard`, `reactivate`, `rotate_secret`, `verify` |
+| `emails` | `send`, `get`, `list`, `update`, `cancel` |
+| `emails.received` | `list`, `address`, `set_address_enabled`, `get`, `raw`, `attachment`, `simulate` |
+| `batch` | `send` (a list of emails, or `recipients=` for one message to many) |
+| `domains` | `create`, `get`, `list`, `update`, `verify`, `remove` |
+| `suppressions` | `create`, `list`, `remove` |
+| `templates` | `create`, `get`, `list`, `update`, `publish`, `rollback`, `versions`, `remove` |
+| `toll_free_verifications` | `options`, `create`, `update`, `submit`, `cancel`, `get`, `list` |
+| `business_verification` | `get`, `save`, `submit` |
+| `auto_topup` | `get` |
+| `topup_cap_requests` | `create`, `list` |
+
+`emails.received.raw` and `emails.received.attachment` return `bytes`. A call that answers 204 (the deletes) returns `None`.
+
+Full API reference: <https://honkio.ca/docs/api>. SDK guide: <https://honkio.ca/docs/sdk>.
+
+## Development
+
+```sh
+uv venv && uv pip install -e '.[dev]'
+ruff check . && mypy --strict src && pytest
+python scripts/generate_types.py   # after web/generated/openapi.json changes
+```
+
+Inside the monorepo, the test suite reads `web/generated/openapi.json` (and the API source) and fails when a route or keyword argument the SDK uses is not in the spec, when `WEBHOOK_EVENTS` differs from the API's list, or when `src/honkio/_types.py` is stale. Those tests skip when run from a checkout without the monorepo.
+
+## License
+
+MIT

honkio-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "honkio"
+dynamic = ["version"]
+description = "Official Python SDK for HonkIO: Canadian SMS and email, CASL built in."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "somethingcorporate" }]
+keywords = ["sms", "email", "casl", "canada", "honkio", "api"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "mypy>=1.10", "ruff>=0.5"]
+
+[project.urls]
+Homepage = "https://honkio.ca/docs/sdk"
+Documentation = "https://honkio.ca/docs/sdk"
+Issues = "https://honkio.ca/contact"
+
+[tool.hatch.version]
+path = "src/honkio/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/honkio"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "scripts", "README.md", "LICENSE", "CHANGELOG.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+filterwarnings = ["error"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+
+[tool.ruff]
+line-length = 110
+target-version = "py310"
+extend-exclude = ["src/honkio/_types.py"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B"]
+# `ruff format` wraps code; the long lines left are docstrings and generated strings.
+ignore = ["E501"]

honkio-0.1.0/scripts/generate_types.py

@@ -0,0 +1,99 @@
+"""Writes src/honkio/_types.py from `components.schemas` in the committed OpenAPI snapshot.
+
+    python scripts/generate_types.py          # rewrite the file
+    python scripts/generate_types.py --check  # exit 1 if the committed file is stale
+
+tests/test_types_drift.py runs `render()` and compares it with the committed file.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).resolve().parents[1]
+SPEC = ROOT.parents[1] / "web" / "generated" / "openapi.json"
+OUT = ROOT / "src" / "honkio" / "_types.py"
+
+HEADER = '''"""Response types for the HonkIO API.
+
+Generated by scripts/generate_types.py from web/generated/openapi.json. Do not edit.
+Every key is optional (total=False): the API may add fields, and a field a call does not return is absent.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, TypedDict
+
+'''
+
+SCALARS = {"string": "str", "integer": "int", "number": "float", "boolean": "bool"}
+
+
+def class_name(schema_name: str) -> str:
+    parts = re.split(r"[^0-9A-Za-z]+", schema_name)
+    name = "".join(p[:1].upper() + p[1:] for p in parts if p)
+    return name if name and not name[0].isdigit() else f"T{name}"
+
+
+def annotate(schema: Any) -> str:
+    if not isinstance(schema, dict):
+        return "Any"
+    ref = schema.get("$ref")
+    if isinstance(ref, str):
+        return repr(class_name(ref.rsplit("/", 1)[-1]))
+    enum = schema.get("enum")
+    if isinstance(enum, list) and enum:
+        literals = [repr(v) for v in enum if v is not None]
+        inner = f"Literal[{', '.join(literals)}]" if literals else "None"
+        return f"Optional[{inner}]" if None in enum and literals else inner
+    kind = schema.get("type")
+    if isinstance(kind, list):
+        kinds = [k for k in kind if k != "null"]
+        if len(kinds) == 1:
+            inner = annotate({**schema, "type": kinds[0]})
+            return f"Optional[{inner}]" if "null" in kind else inner
+        return "Any"
+    if kind in SCALARS:
+        return SCALARS[kind]
+    if kind == "array":
+        return f"List[{annotate(schema.get('items'))}]"
+    if kind == "object":
+        return "Dict[str, Any]"
+    return "Any"
+
+
+def render(spec: dict[str, Any] | None = None) -> str:
+    if spec is None:
+        spec = json.loads(SPEC.read_text(encoding="utf-8"))
+    schemas: dict[str, Any] = spec["components"]["schemas"]
+    entries = sorted((class_name(name), schema) for name, schema in schemas.items())
+    lines = [HEADER]
+    exported = "".join(f"    {name!r},\n" for name, _ in entries)
+    lines.append(f"__all__ = [\n{exported}]\n")
+    for name, schema in entries:
+        properties = schema.get("properties") if isinstance(schema, dict) else None
+        fields = properties if isinstance(properties, dict) else {}
+        body = "".join(f"        {key!r}: {annotate(value)},\n" for key, value in fields.items())
+        mapping = f"{{\n{body}    }}" if body else "{}"
+        lines.append(f"\n{name} = TypedDict(\n    {name!r},\n    {mapping},\n    total=False,\n)\n")
+    return "".join(lines)
+
+
+def main() -> int:
+    text = render()
+    if "--check" in sys.argv:
+        if OUT.read_text(encoding="utf-8") != text:
+            print(f"{OUT} is stale; run python scripts/generate_types.py", file=sys.stderr)
+            return 1
+        return 0
+    OUT.write_text(text, encoding="utf-8")
+    print(f"wrote {OUT}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

honkio-0.1.0/src/honkio/__init__.py

@@ -0,0 +1,53 @@
+"""Official Python SDK for HonkIO: Canadian SMS and email, CASL built in."""
+
+from ._client import AsyncHonkio, Honkio
+from ._core import NOT_GIVEN, NotGiven
+from ._endpoints import ENDPOINTS, Endpoint
+from ._errors import (
+    APIConnectionError,
+    ApiError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    HonkioError,
+    InternalServerError,
+    InvalidArgumentError,
+    InvalidSignatureError,
+    NotFoundError,
+    PaymentRequiredError,
+    PermissionDeniedError,
+    RateLimitError,
+    UnavailableForLegalReasonsError,
+    UnprocessableEntityError,
+)
+from ._version import __version__
+from ._webhooks import WEBHOOK_EVENTS, verify_webhook
+
+__all__ = [
+    "ENDPOINTS",
+    "NOT_GIVEN",
+    "WEBHOOK_EVENTS",
+    "APIConnectionError",
+    "APITimeoutError",
+    "ApiError",
+    "AsyncHonkio",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConflictError",
+    "Endpoint",
+    "Honkio",
+    "HonkioError",
+    "InternalServerError",
+    "InvalidArgumentError",
+    "InvalidSignatureError",
+    "NotGiven",
+    "NotFoundError",
+    "PaymentRequiredError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "UnavailableForLegalReasonsError",
+    "UnprocessableEntityError",
+    "__version__",
+    "verify_webhook",
+]