[Feature][Medium] CI pipeline hardening, type safety improvements, and developer experience gaps

[numbers-official]

Summary

Multiple medium-priority improvements to CI reliability, type safety, and developer experience across both SDKs.

CI/CD Pipeline Issues

1. Feature parity checker never exits non-zero

• scripts/check-feature-parity.py:212-219
• The main() function always exits 0 regardless of parity result. The CI step passes even when features are missing.
• Fix: Add sys.exit(1) when parity is not achieved.

2. sync-versions.py ignores __init__.py version

• scripts/sync-versions.py:103-117
• Only compares package.json and pyproject.toml versions. Does not check __init__.py.__version__, allowing stale runtime version strings.
• Fix: Add third version check for python/numbersprotocol_capture/__init__.py.

3. Python CI tests only Python 3.14 (not yet stable)

• .github/workflows/ci.yml:73-74
• pyproject.toml declares requires-python = ">=3.14" which is aggressive. Code uses no 3.14-specific features.
• Fix: Lower minimum to 3.11+, add matrix ["3.11", "3.12", "3.13"].

4. TypeScript CI tests only Node.js 20

• .github/workflows/ci.yml:52-55
• package.json declares "engines": {"node": ">=18.0.0"} but CI only tests Node 20.
• Fix: Add matrix ["18", "20", "22"].

5. Deprecated softprops/action-gh-release@v1

• .github/workflows/release.yml:122
• v1 depends on Node.js 16 runners that GitHub is phasing out.
• Fix: Update to softprops/action-gh-release@v2.

6. No coverage enforcement or reporting

• .github/workflows/ci.yml
• Python runs pytest without --cov-fail-under. TypeScript has no coverage configured.
• Fix: Add --cov-fail-under=80 for Python; add vitest coverage for TypeScript.

Type Safety & Architecture

7. TypeScript AssetTree index signature undermines type safety

• ts/src/types.ts:144
• [key: string]: unknown disables excess property checking on the entire interface.
• Fix: Replace with extra?: Record<string, unknown> field (matching the Python SDK pattern).

8. Ambiguous timestamp precision undocumented

• ts/src/crypto.ts:29 and python/numbersprotocol_capture/crypto.py:44
• created_at uses milliseconds in integrity proofs, but Commit.timestamp from API uses seconds. No documentation clarifies which.
• Fix: Document in type definitions. Add helper getCreatedDate() method.

9. Hardcoded service URLs not configurable

• ts/src/client.ts:24-31 and python/numbersprotocol_capture/client.py:33-37
• Five different service URLs are hardcoded. Users cannot point to staging environments.
• Fix: Add optional URL overrides in CaptureOptions with current values as defaults.

Developer Experience

10. Missing py.typed marker for PEP 561

• python/numbersprotocol_capture/ directory
• Despite pyproject.toml declaring "Typing :: Typed", the PEP 561 marker file is missing.
• Fix: Create empty python/numbersprotocol_capture/py.typed.

11. TypeScript test coverage significantly lags Python

• ts/src/client.test.ts
• Only tests constructor validation and searchAsset. Zero tests for register(), update(), get(), getHistory(), getAssetTree(), searchNft().
• Fix: Create errors.test.ts, crypto.test.ts, and expand client.test.ts with mock-based tests.

---

Generated by Health Monitor with Omni