ZIP-596: adds taxcloud support for CalculateCart feature

[ericlakich]

This pull request introduces a major update (v0.2.3-beta) to the ZipTax SDK, focusing on comprehensive support for shopping cart tax calculation with dual routing between the ZipTax and TaxCloud APIs. The update adds new models, utilities, and tests, and refactors the main cart calculation method to support both backends transparently. Documentation and versioning are also updated to reflect these changes.

Cart Tax Calculation & Routing Enhancements:

• Added automatic routing in CalculateCart() to TaxCloud's /tax/connections/{connectionId}/carts endpoint when TaxCloud credentials are configured, maintaining the same input contract (CalculateCartRequest) and transforming requests as needed (address parsing, taxabilityCode mapping, line item indexing). The return type is now a union of CalculateCartResponse and TaxCloudCalculateCartResponse.
• Introduced a static method _transform_cart_for_taxcloud() for request transformation, and split cart calculation into two private helpers for ZipTax and TaxCloud backends.

Model and Utility Additions:

• Added address parsing utility parse_address_string() in utils/validation.py to convert single-string addresses to structured components, with robust error handling.
• Introduced three new Pydantic models for TaxCloud cart responses: TaxCloudCalculateCartResponse, TaxCloudCartItemResponse, and TaxCloudCartLineItemResponse, and exported them in __init__.py and models/__init__.py. [1] [2] [3]

Testing and Validation:

• Added 17 new tests in TestCalculateCartTaxCloudRouting to cover routing logic, request/response transformation, and error handling for cart calculation.
• Enforced and documented Pydantic validation constraints for cart models (e.g., item and line item counts, positive price/quantity, currency code). [1] [2]

Documentation and Versioning:

• Updated README.md and CLAUDE.md to document the new cart tax calculation feature, dual-routing behavior, usage examples, and model constraints. [1] [2] [3]
• Bumped version from 0.2.0-beta to 0.2.3-beta in all relevant files. [1] [2] [3] [4]

Technical and Quality Improvements:

• Ensured all quality checks pass (black, ruff, mypy, pytest with 96% coverage), and clarified retry logic applies to both ZipTax and TaxCloud routes.
• Updated exports in __init__.py and models/__init__.py to include new cart and TaxCloud models. [1] [2] [3]

These changes significantly expand the SDK's tax calculation capabilities, improve developer ergonomics, and ensure robust validation and testing.

• Cart Tax Calculation & Routing Enhancements:

  • Automatic routing of CalculateCart() to TaxCloud or ZipTax based on credentials, with request/response transformation and unified input contract.
  • Refactored cart calculation logic into backend-specific helpers and added static method for TaxCloud request transformation.

• Model and Utility Additions:

  • Added address parsing utility and three new Pydantic models for TaxCloud cart responses, with exports updated across modules. [1] [2] [3]

• Testing and Validation:

  • Introduced 17 new tests for cart routing and validation, and enforced/documented Pydantic constraints on cart models. [1] [2]

• Documentation and Versioning:

  • Updated documentation for new features, usage, and constraints; bumped version to 0.2.3-beta in all relevant files. [1] [2] [3] [4] [5]

• Technical and Quality Improvements:

  • Maintained high code quality and coverage, clarified retry logic, and updated module exports for new models. [1] [2] [3] [4]

[Copilot]

Pull request overview

This pull request adds comprehensive support for shopping cart tax calculation with intelligent dual routing between the ZipTax and TaxCloud APIs. The implementation maintains a unified input contract (CalculateCartRequest) while automatically selecting the appropriate backend based on client configuration. When TaxCloud credentials are configured, requests are transformed and routed to TaxCloud's /tax/connections/{connectionId}/carts endpoint with proper address parsing and field mapping.

Changes:

• Added automatic backend routing in CalculateCart() that transparently handles ZipTax and TaxCloud APIs with unified input but distinct response types
• Introduced address parsing utility (parse_address_string()) and three new TaxCloud response models (TaxCloudCalculateCartResponse, TaxCloudCartItemResponse, TaxCloudCartLineItemResponse)
• Added 17 new tests covering routing logic, request transformation, response parsing, and error handling scenarios

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/ziptax/resources/functions.py	Implements dual-routing CalculateCart() with private helpers for ZipTax and TaxCloud backends, plus static transformation method
src/ziptax/utils/validation.py	Adds parse_address_string() utility to convert single-string addresses to structured TaxCloud format
src/ziptax/models/responses.py	Defines 9 ZipTax cart models and 3 TaxCloud cart response models with Pydantic validation constraints
src/ziptax/__init__.py	Exports new cart and TaxCloud models, updates version to 0.2.3-beta
src/ziptax/models/__init__.py	Exports cart calculation and TaxCloud response models
tests/test_functions.py	Adds 17 tests for TaxCloud routing and 9 tests for basic cart functionality with Pydantic validation
tests/conftest.py	Adds fixtures for ZipTax and TaxCloud cart responses
pyproject.toml	Updates version to 0.2.3-beta
docs/spec.yaml	Documents cart endpoint specification with dual-routing behavior and transformation rules
README.md	Adds cart tax calculation usage guide with dual-routing explanation and validation examples
CLAUDE.md	Updates developer documentation with cart calculation patterns and SDK version
CHANGELOG.md	Documents changes for 0.2.3-beta and 0.2.1-beta releases

---

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