isa-sdk 1.0.0__tar.gz

isa_sdk-1.0.0/.gitignore

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

isa_sdk-1.0.0/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog — sah-sdk
+
+All notable changes to the unified Python SDK. Until v1.0.0 ships to
+public PyPI, every release is a pre-release and the API may change in
+incompatible ways.
+
+## 1.0.0rc2 — 2026-05-30
+
+Reference-facade consumer-gap fixes so bpp2.0 can drop its bypasses. The
+underlying release tag is `sdk/v1.0.0-rc.2`.
+
+### Fixed
+
+- **`products_by_family` skips empty-id rows.** A row whose `id` is an
+  empty string is now dropped (was kept), matching the Go/PHP/C# mirrors.
+- **`discontinued_products` accepts integer-valued float epochs.** The
+  strict `isinstance(value, int)` check is replaced by an integer-epoch
+  coercion that keeps integer-valued numbers in any JSON notation
+  (`1700000000.0`) and drops genuine fractionals (`1700000000.5`).
+
+## 1.0.0rc1 — 2026-05-29
+
+First release candidate for the public 1.0 SDK. **Internal channel only**
+(GitHub Packages / Test PyPI). The committed metadata uses PEP 440
+normalized form `1.0.0rc1`; the underlying release tag is
+`sdk/v1.0.0-rc.1`.
+
+### Highlights
+
+- **Per-surface `api_version` map (no global default).**
+  `Isa.with_keycode(api_version={"prequalify": "2026-05-14", ...})`.
+  Surfaces missing from the map fall back to `BUNDLED_API_VERSIONS`.
+- **`BUNDLED_API_VERSIONS` exported.** The full per-surface default
+  table is a public symbol; downstream tooling and conformance
+  scenarios pin against it byte-identically across all 5 languages.
+- **Bundleless top-level `isa.zyins.reference.match(text)`.** Fetches
+  and caches the v3 datasets index transparently. No prior
+  `datasets.get_v3()` required. `refresh_reference_index()`
+  invalidates.
+- **`cases.save` / `cases.recall` via injectable `CaseStorage`.**
+  Default `ZeroKnowledgeCaseStorage` envelopes the payload before
+  writing through `/v1/case`. Carrier adapters implement the same
+  protocol to redirect persistence.
+- **v3 wire-shape end-to-end.** `prequalify` / `quote` accept the
+  nested `applicant` + `coverage` + `products` envelope; `pricing[]`
+  table iteration on offers; ULID-aware conditions/medications;
+  `face_amount_cents` singular.
+- **Idempotency: strict UUID v4** on `/v3/*` mutations. SDK auto-mints
+  per call; consumer override via `idempotency_key=` validated at
+  the transport layer.
+
+### Migration
+
+See [`MIGRATION.md`](./MIGRATION.md) for the 0.x → 1.0 cut and
+[../../MIGRATION.md](../../MIGRATION.md) for the cross-language guide.
+
+### Known drift (conformance gate YELLOW — non-blocking)
+
+The Python conformance runner is PENDING; nine known drift items from
+the TypeScript canonical runner are tracked in PR #387:
+
+1. Bearer auth doesn't reach product methods on the locked surface;
+   `isa.zyins.prequalify` requires `Isa.with_keycode()`.
+2. `applicant.height_inches` (number) vs `applicant.height` (Height
+   object): v3 serializer crashes on scenarios 01,02,03,04,05,12.
+3. Scenario 12 routes through v2, not v3 (no `api_version` map).
+4. `reference.concepts.match` returns `is_known=False` when the v3
+   datasets bundle hasn't been primed (scenarios 03, 07, 09).
+5. `cases.save({applicant, state, note})` rejected; locked
+   `ZeroKnowledgeCaseStorage` requires `{product, payload}`.
+6. `cases.recall(id)` without `recall_token` throws by design;
+   scenario 10 assumes token-optional recall.
+7. `prequalify(req, idempotency_key=...)` not supported on locked
+   signature (scenario 12).
+8. `reference.match` (scenario) vs `reference.concepts.match` (locked).
+9. `reference.conditions_for(id=, sort=)` does not exist; traversal
+   is on the concept handle.
+
+Each is either an SDK fix, a scenario rewrite, or "by design" — the
+gate is YELLOW pending triage.
+
+### Links
+
+- Docs: <https://docs.isaapi.com>
+- Guides: [`api/guides/`](../../api/guides/)
+- Migration: [`MIGRATION.md`](./MIGRATION.md)

isa_sdk-1.0.0/MIGRATION.md

@@ -0,0 +1,140 @@
+# Migration — 0.x → 1.0.0rc1 (Python)
+
+The cross-language guide at [`../../MIGRATION.md`](../../MIGRATION.md)
+covers the full cut (constructor rename, per-surface `api_version`,
+v3 wire-shape, CaseStorage adapter, bundleless `reference.match`).
+Python-specific notes:
+
+- **Install (rc.1, internal channel):**
+
+  ```bash
+  # Test PyPI:
+  pip install --index-url https://test.pypi.org/simple/ \
+      --extra-index-url https://pypi.org/simple/ \
+      sah-sdk==1.0.0rc1
+
+  # OR GitHub Packages for Python (when configured):
+  pip install --index-url https://<token>@pypi.pkg.github.com/Software-Automation-Holdings-LLC/ \
+      sah-sdk==1.0.0rc1
+  ```
+
+  PEP 440 normalization: the release tag is `sdk/v1.0.0-rc.1`; the
+  installable package version is `1.0.0rc1`.
+
+- **Constructor:** `Isa.create(...)` → `Isa.with_keycode(...)`. The
+  `device_id` parameter is removed (internal SDK detail).
+- **api_version:** `str` → `dict[str, str]` (per-surface map). Use
+  `BUNDLED_API_VERSIONS` for defaults.
+- **Cases:** `isa.case.save(...)` → `isa.zyins.cases.save(product=...,
+  payload=...)`. Default storage is `ZeroKnowledgeCaseStorage`.
+- **Reference:** `datasets.get_v3().match(...)` →
+  `isa.zyins.reference.match(text)`. Cache primes on first call;
+  `isa.zyins.reference.refresh()` invalidates.
+- **Type checking:** mypy strict against the SDK now enforces the
+  locked surface contract.
+
+---
+
+# Historical: `isa-sdk-zyins` 0.2.x → `sah-sdk` 0.3.0
+
+## What changed
+
+The Python SDK has consolidated from a per-product package into a single
+unified package. Per `SDK_DESIGN.md` §0 (2026-05-18), there is now **one
+package per language**, with each product mounted under a sub-namespace:
+
+| Before (0.2.x)                | After (0.3.0)                          |
+|-------------------------------|----------------------------------------|
+| `isa-sdk-zyins` (PyPI name)   | `sah-sdk`                              |
+| `isa_sdk.zyins` (import root) | `sah_sdk.zyins`                        |
+| `isa_sdk.zyins.transport`     | `sah_sdk.core.transport`               |
+| `isa_sdk.zyins.errors`        | `sah_sdk.core.errors`                  |
+| `isa_sdk.zyins.envelope`      | `sah_sdk.core.envelope`                |
+| `isa_sdk.zyins.debug`         | `sah_sdk.core.debug`                   |
+| `isa_sdk.zyins.auth`          | `sah_sdk.core.auth`                    |
+| (n/a — was zyins-only)        | `sah_sdk.rapidsign` (scaffold)         |
+| (n/a — was zyins-only)        | `sah_sdk.proxy` (scaffold)             |
+
+All public re-exports remain available at the namespace root —
+`from sah_sdk.zyins import Isa, QuoteInput, PrequalifyResult` still
+works, and `Isa` is additionally exported from the top-level
+(`from sah_sdk import Isa`). Domain types (`Applicant`, `Coverage`,
+`Product`, `Medication`, `Condition`, …) are unchanged.
+
+## Why
+
+- Per-product splits added 20 publish targets (4 products × 5 languages)
+  without realized benefit — bundle size, licensing separation, and
+  release cadence are all addressable at other layers.
+- One mental model: consumers learn `Isa.with_bearer()` once and use the
+  same client for `isa.zyins.*`, `isa.rapidsign.*`, `isa.proxy.*`.
+- Cross-product primitives (auth strategies, error hierarchy, envelope,
+  transport) live in one place and stay in sync.
+
+## Mechanical migration
+
+For most projects, the migration is two find-and-replace operations:
+
+```bash
+# In your project root:
+grep -rl 'from isa_sdk.zyins' src/ | xargs sed -i '' \
+    's/from isa_sdk\.zyins/from sah_sdk.zyins/g'
+
+grep -rl 'isa_sdk\.zyins\.\(transport\|errors\|envelope\|debug\|auth\)' src/ | xargs sed -i '' \
+    -e 's/isa_sdk\.zyins\.transport/sah_sdk.core.transport/g' \
+    -e 's/isa_sdk\.zyins\.errors/sah_sdk.core.errors/g' \
+    -e 's/isa_sdk\.zyins\.envelope/sah_sdk.core.envelope/g' \
+    -e 's/isa_sdk\.zyins\.debug/sah_sdk.core.debug/g' \
+    -e 's/isa_sdk\.zyins\.auth/sah_sdk.core.auth/g'
+```
+
+For projects with non-trivial imports (e.g. that re-export SDK symbols
+from internal facades, or that use the SDK across many packages), use
+the bundled `libcst`-based codemod:
+
+```bash
+pip install 'sah-sdk[dev]'
+python -m sah_sdk._codemod path/to/your/src
+```
+
+The codemod is idempotent — running it twice on already-migrated code
+is a no-op. It only rewrites known import patterns; ambiguous cases are
+left alone with a diagnostic for human review.
+
+## Public surface (0.3.0)
+
+```python
+from sah_sdk import (
+    Isa,
+    # Auth strategies (carry credentials; transport wires them later)
+    BearerAuth, LicenseAuth, SessionAuth,
+    # Errors
+    IsaApiError, IsaIdempotencyConflictError, IsaPermissionError,
+    IsaTransportError, IsaConfigError,
+    # Envelope and value types
+    Envelope, RawResponse, Money, Email, Url,
+    # Constants
+    Product, ProductLabels, UsState, ErrorCode,
+)
+```
+
+## Pinning during transition
+
+If you must support both during transition, pin to the legacy package
+in one place and the new package in another, then migrate file by file:
+
+```toml
+# pyproject.toml
+dependencies = [
+    "isa-sdk-zyins==0.2.*; python_version < '3.10'",  # legacy callers
+    "sah-sdk>=0.3.0",                                   # everything else
+]
+```
+
+The legacy package will receive security backports for six months past
+the 0.3.0 GA date, then be archived.
+
+## Questions / issues
+
+File an issue at <https://github.com/Software-Automation-Holdings-LLC/isa-platform/issues>
+with the `sdk-python` label.

isa_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,328 @@
+Metadata-Version: 2.4
+Name: isa-sdk
+Version: 1.0.0
+Summary: Unified Python SDK for ISA APIs (zyins, rapidsign, proxy).
+Project-URL: Homepage, https://github.com/Software-Automation-Holdings-LLC/isa-platform
+Project-URL: Source, https://github.com/Software-Automation-Holdings-LLC/isa-platform
+Author: Software Automation Holdings, LLC
+License: Apache-2.0
+Keywords: insurance,isa,rapidsign,sdk,zyins
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx>=0.27
+Requires-Dist: libcst>=1.4
+Requires-Dist: pydantic>=2.6
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: libcst>=1.4; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sah-sdk
+
+Python SDK for the [Best Plan Pro API](https://docs.isaapi.com) — powered by the ZyINS engine. Mirrors the
+canonical TypeScript SDK at `packages/zyins/js/` with Python-idiomatic
+naming (`snake_case`) and pydantic v2 models.
+
+## Install
+
+```bash
+pip install sah-sdk
+```
+
+> **GitHub Packages fallback.** Until `sah-sdk` is fully published on PyPI, install directly from the source repository:
+>
+> ```bash
+> pip install "git+https://github.com/Software-Automation-Holdings-LLC/sdk.git@sdk/v0.5.0#subdirectory=packages/python"
+> ```
+>
+> The wire surface is identical either way; only the install command changes.
+
+## Quick start
+
+```python
+import os
+from sah_sdk.zyins import Isa, Applicant, Coverage, PrequalifyInput, Sex
+
+# Reads ISA_TOKEN from the environment — no explicit token needed.
+isa = Isa.with_bearer()
+
+result = isa.zyins.prequalify(PrequalifyInput(
+    applicant=Applicant(
+        dob="1962-04-18",
+        sex=Sex.MALE,
+        height_inches=70,
+        weight_pounds=195,
+        state="NC",
+        nicotine_use="none",
+    ),
+    coverage=Coverage.face_value(100_000),
+    products="colonial-penn.final-expense",
+))
+
+for plan in result.data.plans:
+    print(plan.brand, plan.tier, plan.monthly_premium)
+```
+
+`Isa.with_bearer()` reads `ISA_TOKEN` from the environment. `Authorization: Bearer <token>`,
+`Idempotency-Key`, and the date-pinned `Version` header are set automatically.
+
+## First call in <15 lines
+
+```python
+from sah_sdk.zyins import Isa, Coverage
+
+isa = Isa.with_keycode(
+    keycode="SDV-HWH-WDD",
+    email="john.doe@acme-agency.com",
+)
+result = isa.zyins.prequalify_v2(
+    applicant={"dob": "1962-04-18", "sex": "male", "state": "NC"},
+    coverage=Coverage.face_value(25_000),
+    products="colonial-penn.final-expense",
+)
+print(result.data.plans[0].monthly_premium)
+```
+
+## Per-surface API versions
+
+The ISA API is a federation of independently versioned surfaces. Every SDK
+release exports a frozen `BUNDLED_API_VERSIONS` mapping recording which
+`/vN` each surface targets:
+
+```python
+from sah_sdk.zyins import BUNDLED_API_VERSIONS
+
+print(BUNDLED_API_VERSIONS)
+# {
+#   "prequalify": "v2",
+#   "quote":      "v2",
+#   "datasets":   "v2",
+#   "reference":  "v2",
+#   "sessions":   "v1",
+#   "branding":   "v1",
+#   "cases":      "v1",
+# }
+```
+
+Pin individual surfaces with a per-surface `api_version` map. There is **no**
+`default` key and **no** string shorthand — resolution is
+`api_version.get(surface, BUNDLED_API_VERSIONS[surface])`:
+
+```python
+isa = await Isa.with_keycode(
+    keycode="SDV-HWH-WDD",
+    email="john.doe@acme-agency.com",
+    api_version={"quote": "v2"},   # pin only quote; everything else bundled
+)
+```
+
+The release that retargets `prequalify` / `quote` / `datasets` / `reference`
+to `v3` will bump those entries. See [SDK syntax proposal §2.7][syntax-27].
+
+[syntax-27]: ../../docs/sdk-syntax-proposal.md#27-versioning--per-surface-not-global
+
+## Reference data — `.match()`
+
+The unversioned `isa.zyins.reference` namespace canonicalizes free-text
+medication and condition input. Unknown text never rejects — it returns a
+structured envelope so the final canonicalization fires server-side at
+`/vN/prequalify`:
+
+```python
+ds = await isa.zyins.datasets.get(include=["conditions", "medications"])
+
+insulin = isa.zyins.medications.match("insulin")
+print(insulin.id, insulin.name, insulin.is_known)
+# med_01KSR2WVAGC05ZGR6FA4QYEB12  INSULIN  True
+
+# Symmetric traversal — what conditions is insulin used for?
+used_for = insulin.conditions(isa.zyins.reference.Sort.MOST_COMMON_FIRST)
+# frequency-ordered list; cond_01KSR2WVAGC05ZGR6FA4QYEA8X first
+
+novel = isa.zyins.medications.match("NewExperimental XR 2026")
+# → {"is_known": False, "input_text": "NewExperimental XR 2026", ...}
+```
+
+`Sort.MOST_COMMON_FIRST` and `Sort.ALPHABETICAL` are the two supported
+orderings.
+
+## Case storage — bring your own
+
+`isa.zyins.cases.*` routes through a `CaseStorage` adapter. The default is
+the zero-knowledge store — ISA's servers only hold ciphertext and an opaque
+ID. To plug a carrier-controlled store, pass your adapter at construction:
+
+```python
+isa = await Isa.with_keycode(
+    keycode=..., email=...,
+    case_storage=CarrierCaseStorage(),   # optional; default = ZeroKnowledgeCaseStorage
+)
+```
+
+See [cases guide](https://docs.isaapi.com/docs/cases) for the full
+bring-your-own pattern.
+
+## Auth deviation from the TS SDK
+
+The TypeScript SDK in this monorepo still carries the pre-#286 HMAC device
+signing surface (`AuthContext` with `licenseKey + orderId + email + deviceId`).
+The Python SDK is built against the post-#286 wire contract: a single
+bearer token (`isa_live_*` / `isa_test_*`) is the entire auth surface.
+This is the intentional simplification called out in the platform's
+`platform_v1_architecture` notes.
+
+## Surface
+
+| TypeScript                                | Python                              |
+| ----------------------------------------- | ----------------------------------- |
+| `client.prequalify(req)`                  | `client.prequalify.run(input)`      |
+| `client.license.activate/deactivate/check`| `client.license.*` (mirrored)       |
+| `client.case.email(req)`                  | `client.case.email(input)`          |
+| (new)                                     | `client.quote.run(input)`           |
+| (new)                                     | `client.datasets.list/get`          |
+| (new)                                     | `client.reference_data.get(kind)`   |
+| (new)                                     | `client.usage.summary(period)`      |
+
+Errors mirror the TS hierarchy: `ISAError` (alias `ZyInsError`, also
+exported as `IsaApiError`) → `LicenseError`, `PrequalifyError`,
+`ValidationError`, `RateLimitError`, `AuthError`,
+`IsaIdempotencyConflictError`.
+
+## `Isa` factory client
+
+Per [SDK_DESIGN.md §3](https://github.com/Software-Automation-Holdings-LLC/isa-platform/blob/main/docs/SDK_DESIGN.md),
+the recommended entry point is the `Isa` class with three named factories:
+
+```python
+from sah_sdk.zyins import Isa
+
+# Reads ISA_TOKEN from the environment.
+isa = Isa.with_bearer()
+env = isa.zyins.prequalify(req)
+print(env.data, env.request_id, env.idempotency_key, env.retry_attempts)
+
+# Or pass the token explicitly.
+isa = Isa.with_bearer("isa_live_…")
+
+# License factory — reads ISA_LICENSE_KEYCODE / ISA_LICENSE_EMAIL.
+isa = Isa.with_license()
+
+# Session factory — reads ISA_SESSION_ID / ISA_SESSION_SECRET.
+isa = Isa.with_session()
+```
+
+Each factory raises `IsaConfigError` with a clear, actionable message if
+the required env vars are unset and no explicit arguments are supplied.
+
+### Raw HTTP access
+
+Every method has a `.with_raw_response()` variant returning both the
+parsed envelope and the underlying HTTP metadata:
+
+```python
+env, raw = isa.zyins.prequalify.with_raw_response(req)
+raw.status     # int
+raw.url        # str
+raw.headers    # read-only mapping
+```
+
+### Debug logging
+
+Set `ISA_LOG=debug` to dump every request and response to **stderr** —
+never stdout, so parent processes piping the consumer's JSON output stay
+clean. Credential headers (`Authorization`, `X-Device-Signature`,
+`X-Session-Signature`) and PII body fields (`email`, `dob`, `ssn`,
+`phone`) are redacted automatically.
+
+### Idempotency conflicts
+
+When the same `Idempotency-Key` is replayed with a different body the
+server returns 409 `idempotency_conflict`. The SDK raises
+`IsaIdempotencyConflictError` with `.key` and `.first_seen_at` so the
+caller can audit the queued-write bug class:
+
+```python
+from sah_sdk.zyins import IsaIdempotencyConflictError
+
+try:
+    isa.zyins.prequalify(req, idempotency_key="case-42")
+except IsaIdempotencyConflictError as e:
+    log.error("key %s first seen at %s", e.key, e.first_seen_at)
+```
+
+## Concurrency
+
+The `Isa` client is safe for use with `asyncio.gather` and
+`concurrent.futures` — every request mints a fresh request-id and
+idempotency key, and shared client state (auth, base URL, debug logger)
+is read-only after construction. Reuse a single `Isa` instance across
+all concurrent requests; the underlying HTTP transport pools connections
+for you.
+
+```python
+import asyncio
+from sah_sdk.zyins import Isa
+
+isa = Isa.with_bearer()
+
+async def one(req):
+    return isa.zyins.prequalify(req)
+
+results = await asyncio.gather(*(one(r) for r in batch))
+# Each result.request_id is distinct.
+```
+
+## Development
+
+```bash
+hatch run test         # pytest
+hatch run lint         # ruff + mypy --strict
+hatch build            # wheel + sdist
+```
+
+Live-integration tests run only when `ZYINS_TEST_TOKEN` is set:
+
+```bash
+ZYINS_TEST_TOKEN=isa_test_... hatch run test -- -m integration
+```
+
+## Licenses and Ready
+
+The Python SDK exposes the public BPP license-lifecycle surface and the
+platform readiness probe on every `ZyInsClient`:
+
+```python
+from sah_sdk.zyins import LicenseCheckInput, ZyInsClient
+
+client = ZyInsClient("isa_live_...")
+
+result = client.license.check(
+    LicenseCheckInput(
+        email="john.doe@acme-agency.com",
+        keycode="ABC-123-XYZ",
+        device_id="dev_01HZK2N5GQR9T8X4B6FJW3Y1AS",
+    )
+)
+# result.status: "valid" | "invalid" | "inactive"
+
+ready = client.health.get_readiness()
+# ready.ready: True on every required probe = "serving"
+```
+
+The pre-existing `client.license` (singular) sub-client targets the
+authenticated `/v1/license/*` self-status endpoints and is untouched.