ZIP-643: adds TIC search to the SDK#9
Conversation
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| /** Full description of the recommended TIC (snake_case to match API) */ | ||
| tic_description: string; | ||
| /** Original product description sent in the query (snake_case to match API) */ | ||
| product_description: string; |
There was a problem hiding this comment.
🔴 ProductCodeRecommendation uses snake_case fields violating CLAUDE.md naming convention
The ProductCodeRecommendation interface introduces tic_description and product_description fields in snake_case. CLAUDE.md mandates under "Key Design Decisions" that the naming convention is "camelCase for all fields" and under "Important Type Conventions" that "ZipTax Responses: Use camelCase (e.g., baseRates, taxSummaries)". The only documented exception is Account Metrics (V60AccountMetrics), which is explicitly called out as using snake_case. These new endpoints go through the ZipTax HTTP client (this.httpClient at src/client.ts:206 and src/client.ts:239), making them ZipTax responses subject to the camelCase convention. Every other field in this same interface (ticId, naturalLabel) correctly uses camelCase, making the inconsistency within a single interface even more problematic.
Prompt for agents
The ProductCodeRecommendation interface at src/models/responses.ts:413-429 has two snake_case fields (tic_description and product_description) that violate the CLAUDE.md naming convention requiring camelCase for ZipTax response types. The only documented exception is V60AccountMetrics.
Two approaches to fix:
1. If the API actually returns snake_case for these fields, rename them to camelCase (ticDescription, productDescription) and add a response transformation layer, or update CLAUDE.md to document this as another exception.
2. If the API returns camelCase, simply rename the fields to ticDescription and productDescription.
Also update the test mock data in tests/client.test.ts (lines 486-488 and 540-542) to use the corrected field names.
Was this helpful? React with 👍 or 👎 to provide feedback.
1 participant
This pull request introduces new AI-powered product code (TIC) search and recommendation features to the SDK, along with supporting types, validation, and comprehensive tests. These additions allow users to search for and receive recommendations for product codes based on natural language descriptions, improving the ease and accuracy of tax code selection.
New Product Code (TIC) Search & Recommendation Features
searchProductCodes()method toZiptaxClientfor searching product codes by natural language description, returning all matching TICs ranked and scored by relevance.recommendProductCode()method toZiptaxClientfor getting an AI-powered product code recommendation, returning the best-match TIC with higher accuracy.validateProductQuery()to ensure product queries are non-empty strings and ≤500 characters.Type & Model Additions
ProductCodeSearchRequest,ProductCodeSearchResult,ProductCodeSearchResponse,ProductCodeRecommendation, andProductCodeRecommendationResponseto support the new endpoints.Testing
searchProductCodes()andrecommendProductCode(), including validation checks and response structure assertions.Documentation & Versioning
CHANGELOG.mdto document the new features in version0.2.3-beta.0.2.3-betainpackage.json.