ZIP-562/v0.2.0-beta

.env.example

@@ -1,3 +1,8 @@
 # ZipTax API Key
 # Get your API key from https://www.zip-tax.com/
-ZIPTAX_API_KEY=your-api-key-here
+ZIPTAX_API_KEY=your-api-key-here
+
+# TaxCloud Credentials (optional - required for order management)
+# Get your credentials from https://taxcloud.com/
+TAXCLOUD_CONNECTION_ID=your-connection-id-here
+TAXCLOUD_API_KEY=your-taxcloud-api-key-here

.github/workflows/README.md

@@ -0,0 +1,168 @@
+# GitHub Actions Workflows
+
+This directory contains automated workflows for the ZipTax Node.js SDK.
+
+## Workflows
+
+### 1. Test (`test.yml`)
+
+**Triggers**: Push to `main`, Pull Requests to `main`
+
+Runs comprehensive quality checks:
+
+- **Lint**: ESLint validation
+- **Type Check**: TypeScript type validation
+- **Format Check**: Prettier formatting validation
+- **Test**: Unit tests across Node.js 18.x, 20.x, 22.x on Ubuntu, macOS, Windows
+- **Coverage**: Test coverage with Codecov integration (requires 80%+)
+
+### 2. Version Check (`version-check.yml`)
+
+**Triggers**: Pull Requests to `main` (opened, synchronized, reopened, labeled, unlabeled)
+
+Enforces semantic versioning:
+
+- **Version Comparison**: Ensures `package.json` version is bumped from base branch
+- **Semantic Validation**: Validates version follows [Semantic Versioning](https://semver.org/)
+- **CHANGELOG Check**: Warns if CHANGELOG.md is not updated
+- **PR Comments**: Posts detailed feedback with bump type and guidance
+- **Skip Option**: Can be bypassed with `skip-version-check` label for docs-only changes
+
+#### Version Check Details
+
+The workflow will:
+1. ✅ **Pass** if version is properly bumped (major, minor, patch, or prerelease)
+2. ❌ **Fail** if version is not bumped or is invalid
+3. ⚠️ **Warn** if CHANGELOG.md is not updated
+4. 🏷️ **Skip** if PR has `skip-version-check` label
+
+#### Usage
+
+**Before creating a PR**, bump the version appropriately:
+
+```bash
+# Breaking changes (0.2.0-beta → 1.0.0)
+npm version major
+
+# New features, backward compatible (0.2.0-beta → 0.3.0-beta)
+npm version minor
+
+# Bug fixes, backward compatible (0.2.0-beta → 0.2.1-beta)
+npm version patch
+
+# Prerelease versions (0.2.0 → 0.2.1-beta.0)
+npm version prerelease --preid=beta
+```
+
+**Update CHANGELOG.md**:
+- Document changes under `[Unreleased]` section
+- Follow existing format (Added, Changed, Fixed, etc.)
+
+**Skip version check** (docs-only changes):
+- Add `skip-version-check` label to the PR
+- Only use for documentation, CI/CD, or repo maintenance changes
+
+### 3. Publish (`publish.yml`)
+
+**Triggers**:
+- GitHub Releases (when created)
+- Manual dispatch with tag input
+
+Publishes package to npm:
+
+- **Quality Checks**: Runs tests, linting, type checking
+- **Build**: Creates distribution files
+- **Publish**: Publishes to npm with provenance
+
+#### Manual Publishing
+
+1. Create a release on GitHub with a version tag (e.g., `v0.2.0-beta`)
+2. Workflow automatically publishes to npm
+3. Prerelease versions (e.g., `-beta`) are published under the `beta` dist-tag, not `latest`
+4. Or trigger manually via Actions tab with a specific tag
+
+**Required Secret**: `NPM_TOKEN` must be configured in repository secrets
+
+## Status Badges
+
+Add these badges to your README.md:
+
+```markdown
+[![Test](https://github.com/ziptax/ziptax-node/actions/workflows/test.yml/badge.svg)](https://github.com/ziptax/ziptax-node/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/ziptax/ziptax-node/branch/main/graph/badge.svg)](https://codecov.io/gh/ziptax/ziptax-node)
+```
+
+## Troubleshooting
+
+### Version Check Fails
+
+**Problem**: PR fails version check even though you bumped the version
+
+**Solutions**:
+1. Ensure you're comparing against the correct base branch (`main`)
+2. Verify `package.json` version follows semantic versioning (x.y.z)
+3. Check that new version is greater than base branch version
+4. For docs-only changes, add `skip-version-check` label
+
+### Test Coverage Below 80%
+
+**Problem**: Coverage check fails
+
+**Solutions**:
+1. Add tests for new code
+2. Run `npm run test:coverage` locally to identify gaps
+3. Ensure all new functions/methods have test coverage
+
+### Publish Fails
+
+**Problem**: Publish workflow fails with authentication error
+
+**Solutions**:
+1. Verify `NPM_TOKEN` secret is configured correctly
+2. Ensure token has publish permissions
+3. Check that package name is available on npm
+
+## Best Practices
+
+1. **Always bump version** in PRs that include code changes
+2. **Update CHANGELOG.md** with all changes
+3. **Run tests locally** before pushing: `npm test`
+4. **Check formatting**: `npm run format:check`
+5. **Validate types**: `npm run type-check`
+6. **Review CI failures** and fix before merging
+
+## Semantic Versioning Guide
+
+Following [SemVer](https://semver.org/):
+
+- **Major (X.0.0)**: Breaking changes, incompatible API changes
+  - Example: Removing a public method, changing return types (0.2.0-beta -> 1.0.0)
+
+- **Minor (0.X.0)**: New features, backward compatible
+  - Example: Adding new methods, new optional parameters (0.2.0-beta -> 0.3.0-beta)
+
+- **Patch (0.0.X)**: Bug fixes, backward compatible
+  - Example: Fixing bugs, typos, performance improvements (0.2.0-beta -> 0.2.1-beta)
+
+- **Prerelease (0.0.0-beta.X)**: Pre-production versions
+  - Example: Beta releases, release candidates (0.2.0 -> 0.2.1-beta.0)
+
+## Contributing
+
+When contributing:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Bump version appropriately
+5. Update CHANGELOG.md
+6. Run all checks locally
+7. Create a Pull Request
+8. Wait for CI to pass
+9. Address any feedback
+
+## Questions?
+
+- Review workflow files for implementation details
+- Check [GitHub Actions documentation](https://docs.github.com/en/actions)
+- Open an issue if you encounter problems

.gitignore

@@ -137,3 +137,6 @@ dist
 # Vite logs files
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
+
+# Generated version file (created by scripts/generate-version.js)
+src/version.ts

CHANGELOG.md

@@ -5,25 +5,63 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.0.0] - 2024-01-15
+## [0.2.0-beta] - 2026-02-16
 
 ### Added
-- Initial release of ZipTax Node.js SDK
-- Support for GetSalesTaxByAddress API endpoint
-- Support for GetSalesTaxByGeoLocation API endpoint
-- Support for GetAccountMetrics API endpoint
+- TaxCloud API integration for order management (optional)
+  - `createOrder()` - Create orders from marketplace transactions, pre-existing systems, or bulk uploads
+  - `getOrder()` - Retrieve a specific order by ID from TaxCloud
+  - `updateOrder()` - Update an existing order's completedDate in TaxCloud
+  - `refundOrder()` - Create partial or full refunds against an order in TaxCloud
+- `getRatesByPostalCode()` - Get sales and use tax rates by 5-digit US postal code
+- New configuration options: `taxCloudConnectionId` and `taxCloudAPIKey` for TaxCloud credentials
+- Comprehensive TypeScript types for all TaxCloud API models (addresses, orders, refunds, currency, exemptions)
+- Full type exports for all public types including TaxCloud models and postal code types
+- `ZiptaxConfigurationError` thrown when TaxCloud methods are called without credentials
+- API response-body error checking for invalid API keys (HTTP 200 with error code 101)
+- TaxCloud example script (`examples/taxcloud-orders.ts`)
+- GitHub Actions workflow for semantic version enforcement on PRs (`version-check.yml`)
+- CONTRIBUTING.md with contribution guidelines and versioning requirements
+- CLAUDE.md project context file for AI assistants
+
+### Changed
+- Client initialization now supports optional TaxCloud credentials alongside ZipTax API key
+- Enhanced HTTP client with PATCH method support for TaxCloud order updates
+- Dynamic User-Agent header now uses package version (`ziptax-node/0.2.0-beta`) instead of hardcoded value
+- `V60AccountMetrics` type corrected to use `request_count`, `request_limit`, `usage_percent`, `is_active`, `message` fields (matching actual API response)
+- Historical date parameter format corrected to `YYYYMM` (e.g., `202401`) across all endpoints and documentation
+- `refundOrder()` request parameter is now optional - omitting items creates a full refund per TaxCloud API spec
+- `RefundTransactionRequest.items` made optional to support full refunds
+- `RefundTransactionResponse.returnedDate` made optional to match API behavior
+
+### Fixed
+- Invalid API key now correctly throws `ZiptaxAuthenticationError` instead of returning error in response body
+- `verifyTaxCloudCredentials()` now throws `ZiptaxConfigurationError` instead of generic `Error`
+- Historical date validation regex corrected from `/^[0-9]{4}-[0-9]{2}$/` to `/^[0-9]{6}$/`
+- Removed unused `TaxCloudHTTPClientConfig` interface from HTTP client
+- Fixed Prettier formatting across all source files
+
+## [0.1.4-beta] - 2024-01-15
+
+### Added
+- Initial beta release of ZipTax Node.js SDK
+- Support for `getSalesTaxByAddress()` API endpoint
+- Support for `getSalesTaxByGeoLocation()` API endpoint
+- Support for `getAccountMetrics()` API endpoint
 - Full TypeScript support with comprehensive type definitions
 - Automatic retry logic with exponential backoff
 - Request/response logging
-- Comprehensive error handling with custom error types
+- Comprehensive error handling with custom error types:
+  - `ZiptaxError` (base), `ZiptaxAPIError`, `ZiptaxAuthenticationError`
+  - `ZiptaxRateLimitError`, `ZiptaxValidationError`, `ZiptaxNetworkError`, `ZiptaxRetryError`
 - Support for both CommonJS and ES Modules
 - 80%+ test coverage
 - Complete documentation and examples
 
 ### Features
 - Promise-based async/await API
-- Configurable retry options
-- Input validation
-- Rate limit handling
+- Configurable retry options with exponential backoff
+- Input validation for all parameters
+- Rate limit handling with retry-after support
 - Network error handling
-- Authentication error handling
+- Authentication error handling