release: v0.1.1 — drop PhoneResult patches, regen from spec 1.0.3

postio-api 1.0.3 ships an aligned spec and runtime: PhoneResult.isReachable
is now boolean|null (matches the HLR return), and the runtime always emits
every nullable field as explicit null instead of dropping them on parse
failure. The hand-patches that papered over the drift are no longer needed.

postio/_models.py is now generated verbatim from @postio/openapi@1.0.3.

Author: Oliver Kingston

CLAUDE.md

@@ -119,20 +119,12 @@ version lives in the response envelope and is independent of SDK
 ergonomics changes. Stay on `0.x` until the API contract is committed
 stable; bump to `1.0` only with a real public-API freeze.
 
-## Spec drift
+## Spec ↔ runtime alignment
 
-`postio/_models.py` is generated, but a couple of fields need manual
-patches to reflect runtime reality:
-
-1. **`PhoneResult`** — every nullable field is patched to `= None`
-   default. The spec marks them `required` with type `[string, null]`,
-   but on invalid input the live API drops them entirely.
-2. **`PhoneResult.isReachable`** — patched to `bool | str | None`. Spec
-   says string-only; live API returns `bool`.
-
-`scripts/codegen.py` prints a reminder of these patches on every regen.
-When postio-api ships a spec/runtime alignment, drop the patches and
-let the generator drive `_models.py` verbatim.
+As of `@postio/openapi@1.0.3` (postio-api 1.0.3), the generated
+`_models.py` is shipped verbatim — no hand-patches required. If a
+future spec change re-introduces drift, prefer fixing it at the source
+(postio-api Zod schemas + handlers) over patching downstream.
 
 ## Secrets the CI needs
 

postio/_models.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
-#   filename:  postio-openapi.json
-#   timestamp: 2026-05-02T13:39:32+00:00
+#   filename:  openapi.json
+#   timestamp: 2026-05-02T20:02:36+00:00
 
 from __future__ import annotations
 
@@ -82,11 +82,11 @@ class Deliverability(Enum):
     Aggregated verdict.
     """
 
-    deliverable = "deliverable"
-    undeliverable = "undeliverable"
-    risky = "risky"
-    unknown = "unknown"
-    invalid = "invalid"
+    deliverable = 'deliverable'
+    undeliverable = 'undeliverable'
+    risky = 'risky'
+    unknown = 'unknown'
+    invalid = 'invalid'
 
 
 class EmailResult(BaseModel):
@@ -99,33 +99,26 @@ class EmailResult(BaseModel):
     mxFound: bool
     smtpCheck: str | None
     isCatchAll: bool | None
-    deliverability: Deliverability = Field(..., description="Aggregated verdict.")
+    deliverability: Deliverability = Field(..., description='Aggregated verdict.')
 
 
 class PhoneResult(BaseModel):
-    # SPEC DRIFT (2026-05-02): spec marks all optional fields as `required`
-    # with type `[string, null]`, but on invalid input the live API omits
-    # them entirely (instead of returning null). Until postio-api aligns
-    # spec with runtime, default every nullable field to None on this model
-    # so customers don't get a parse error on real responses. Also: the live
-    # API returns `bool` for `isReachable` even though the spec says string.
-    # Reapply this block after every codegen.
     number: str
     isValid: bool
     isPossible: bool
-    type: str | None = None
-    countryCode: str | None = None
-    countryName: str | None = None
-    nationalFormat: str | None = None
-    internationalFormat: str | None = None
-    e164Format: str | None = None
-    originalCarrier: str | None = None
-    currentCarrier: str | None = None
-    isPorted: bool | None = None
-    isReachable: bool | str | None = None
-    mcc: str | None = None
-    mnc: str | None = None
-    level: str | None = None
+    type: str | None
+    countryCode: str | None
+    countryName: str | None
+    nationalFormat: str | None
+    internationalFormat: str | None
+    e164Format: str | None
+    originalCarrier: str | None
+    currentCarrier: str | None
+    isPorted: bool | None
+    isReachable: bool | None
+    mcc: str | None
+    mnc: str | None
+    level: str | None
     lookupError: str | None = None
 
 

postio/_version.py

@@ -1 +1 @@
-__version__ = "0.1.0"
+__version__ = "0.1.1"

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "postio"
-version = "0.1.0"
+version = "0.1.1"
 description = "Python SDK for the Postio API — UK address, email, and phone validation. PAF + Ordnance Survey backed. Sync + async, type-safe via Pydantic v2."
 readme = "README.md"
 requires-python = ">=3.10"

scripts/codegen.py

@@ -1,9 +1,9 @@
 #!/usr/bin/env python3
 """Regenerate ``postio/_models.py`` from the live OpenAPI spec.
 
-Pulls https://postio.co.uk/openapi.json, runs datamodel-code-generator into
-``postio/_models.py``, then prints a reminder about manual patches that need
-to be reapplied.
+Pulls https://postio.co.uk/openapi.json and runs datamodel-code-generator
+into ``postio/_models.py``. As of @postio/openapi@1.0.3 no hand-patches
+are needed — the generated model is shipped verbatim.
 
 Usage:
 
@@ -25,24 +25,6 @@
 REPO = Path(__file__).resolve().parent.parent
 TARGET = REPO / "postio" / "_models.py"
 
-# Manual patches that must survive every regen. Keep this list in sync with
-# the comments in ``_models.py``. Each patch is described as:
-#   1. The runtime drift it papers over.
-#   2. The exact change to make.
-PATCHES_REMINDER = """
-After every regen, reapply these manual patches in postio/_models.py:
-
-  PhoneResult — spec marks every nullable field as `required` and the API
-                drops them on invalid input. Add `= None` defaults to every
-                str | None / bool | None field (number, isValid, isPossible
-                stay required). Also: change `isReachable: str | None` to
-                `isReachable: bool | str | None = None` because the live
-                API returns booleans there.
-
-If postio-api ever ships a spec/runtime alignment, drop the patches and let
-the regen drive the model verbatim.
-"""
-
 
 def fetch_spec(dest: Path, source: str) -> None:
     if source.startswith(("http://", "https://")):
@@ -90,7 +72,6 @@ def main() -> int:
         run_codegen(spec_path, TARGET)
 
     print(f"\nwrote {TARGET}")
-    print(PATCHES_REMINDER)
     return 0