ZIP-568/v0.2.1-beta

[ericlakich]

This pull request introduces a major new feature to the SDK: cart tax calculation with automatic origin/destination sourcing, along with comprehensive documentation, new Pydantic models, and test coverage. The update also bumps the SDK version to 0.2.1-beta. The most important changes are grouped below.

Cart Tax Calculation Feature:

• Added the CalculateCart() function, which calculates sales tax for a shopping cart by sending a CalculateCartRequest to the new POST /calculate/cart endpoint on the ZipTax API. The function returns per-item tax rates and amounts via CalculateCartResponse. [1] [2] [3]
• Implemented automatic origin/destination sourcing logic in CalculateCart(). The SDK looks up both addresses, determines interstate/intrastate status, and applies state-specific sourcing rules before sending the request. [1] [2] [3]

Data Modeling and Validation:

• Introduced 9 new Pydantic models for cart tax calculation, including request/response types (CalculateCartRequest, CartItem, CartLineItem, CartCurrency, etc.) with strict validation constraints (e.g., positive price/quantity, USD currency, item count limits). [1] [2]
• Added Pydantic validation to enforce business rules at model construction (e.g., single cart per request, 1-250 line items per cart, required fields). [1] [2]

Documentation and Examples:

• Expanded the README with a usage guide, code examples, and detailed explanation of origin/destination sourcing rules for cart tax calculation. [1] [2]
• Updated the OpenAPI spec (docs/spec.yaml) with the new endpoint, request/response models, validation rules, and sourcing logic. [1] [2]

Testing and Quality:

• Added 122 new tests covering state extraction, sourcing resolution, cart calculation, and validation, achieving 96% code coverage.
• Ensured all quality checks pass (black, ruff, mypy, pytest).

Versioning and Miscellaneous:

• Bumped the SDK version from 0.2.0-beta to 0.2.1-beta in all relevant files and documentation. [1] [2] [3]

These changes provide a robust foundation for cart-based tax calculation in the SDK, with strict validation, clear documentation, and strong test coverage.

[Copilot]

Pull request overview

This PR introduces a comprehensive cart tax calculation feature with automatic origin/destination sourcing to the ZipTax Python SDK. The feature enables calculating sales tax for shopping carts with multiple line items while automatically determining whether to use origin-based or destination-based tax rates according to state-specific sourcing rules. The implementation includes 9 new Pydantic models, 122 tests achieving 96% code coverage, extensive documentation updates, and a version bump to 0.2.1-beta.

Changes:

• Added CalculateCart() function with automatic origin/destination sourcing that looks up both addresses via the V60 API, determines interstate vs. intrastate status, and applies state-specific sourcing rules before calculating taxes
• Introduced 9 new Pydantic models (CalculateCartRequest, CartItem, CartAddress, CartCurrency, CartLineItem, CalculateCartResponse, CartItemResponse, CartLineItemResponse, CartTax) with strict validation constraints for cart tax calculation
• Comprehensive documentation including README usage guide, OpenAPI specification updates, and actual API request/response examples

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/ziptax/resources/functions.py	Implements CalculateCart() function with _extract_state_from_normalized_address() and _resolve_sourcing_address() helpers for automatic sourcing resolution
src/ziptax/models/responses.py	Defines 9 new Pydantic models for cart tax calculation with validation constraints (positive prices/quantities, USD currency, item count limits)
src/ziptax/models/init.py	Exports new cart calculation models to module API
src/ziptax/init.py	Exports new models at package level and updates version to 0.2.1-beta
tests/test_functions.py	Adds 25 new tests across 3 test classes covering state extraction, sourcing resolution, cart calculation, API integration, and Pydantic validation
tests/conftest.py	Adds sample_calculate_cart_response fixture and _build_v60_response helper with 4 state-specific fixtures for testing
README.md	Adds cart tax calculation usage guide with code examples and origin/destination sourcing explanation
CHANGELOG.md	Documents all changes for version 0.2.1-beta release
CLAUDE.md	Updates internal documentation with cart calculation patterns and version
docs/spec.yaml	Adds comprehensive CalculateCart endpoint specification including validation rules, sourcing logic, and example responses
pyproject.toml	Updates package version to 0.2.1-beta

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.