Kintsugi Tax Estimation CLI

An interactive Ruby CLI application for tax estimation using the Kintsugi Tax Platform SDK.

Prerequisites

• Ruby 3.2 or higher (Currently using Ruby 3.2.2)
• Kintsugi API Key
• Kintsugi Organization ID

Installation

1. Clone or download this repository
2. Install dependencies:

bundle install

3. Make the script executable:

chmod +x kintsugi_cli.rb

Usage

Run the CLI application:

ruby kintsugi_cli.rb

Or if you made it executable:

./kintsugi_cli.rb

First Time Setup

When you first run the application, you'll be prompted to:

1. Enter your Kintsugi API Key - This will be masked for security
2. Enter your Organization ID - Your Kintsugi organization identifier
3. Enable Debug Logging - Optional for troubleshooting

Main Menu Options

🏠 Create Tax Estimation

Interactive wizard to create a tax estimation request:

• Transaction Details: External ID, total amount, currency, date
• Address Information: Shipping address with validation
• Transaction Items: Multiple items with categories and quantities
• Review & Submit: Preview the request before submission

📊 View Sample Request

Displays the example request structure from the Kintsugi documentation.

⚙️ Settings

• Update Credentials: Change API key or organization ID
• Toggle Debug Logging: Enable/disable debug output

❌ Exit

Safely exit the application.

Example Request Structure

The CLI creates requests in this format:

{
  "addresses": [
    {
      "city": "Austin",
      "country": "US",
      "postal_code": "78701",
      "state": "TX",
      "street_1": "789 Pine St",
      "type": "SHIP_TO"
    }
  ],
  "currency": "USD",
  "date": "2025-08-19T13:01:29.949000000Z",
  "external_id": "txn_12345",
  "marketplace": false,
  "total_amount": 200.0,
  "transaction_items": [
    {
      "external_id": "Product-001",
      "amount": 100.0,
      "date": "2025-08-19T10:00:00.000000000Z",
      "product_category": "PHYSICAL",
      "product_subcategory": "PHYSICAL_GENERAL",
      "quantity": 2.0
    }
  ]
}

Supported Features

Currencies

• USD (US Dollar)
• EUR (Euro)
• GBP (British Pound)
• CAD (Canadian Dollar)

Countries

• US (United States)
• CA (Canada)
• GB (United Kingdom)
• DE (Germany)
• FR (France)

Product Categories

• PHYSICAL
• DIGITAL
• SERVICE

Product Subcategories

• PHYSICAL_GENERAL
• DIGITAL_GENERAL
• SERVICE_GENERAL

Output

The CLI displays tax estimation results in a formatted table showing:

• External ID
• Total Amount
• Tax Amount
• Tax Rate
• Detailed tax breakdown (if available)

Results can be saved to JSON files for further processing.

Error Handling

The application includes comprehensive error handling for:

• Invalid API credentials
• Network connectivity issues
• Invalid input data
• API response errors

Development

For development and debugging:

bundle exec pry

Dependencies

• kintsugi_sdk (~> 5.5.9) - Official Kintsugi Ruby SDK
• tty-prompt (~> 0.23.1) - Interactive command line prompts
• tty-table (~> 0.12.0) - Terminal table rendering
• tty-spinner (~> 0.9.3) - Terminal spinners for loading states
• colorize (~> 1.1) - Terminal color output

Security Notes

• API keys are masked during input
• No credentials are stored persistently
• All communication uses the official Kintsugi SDK
• Debug logging can be toggled on/off

Troubleshooting

Common Issues

1. "Failed to initialize client"

   • Verify your API key and organization ID
   • Check your internet connection
   • Ensure you have the correct permissions

2. "Tax estimation failed"

   • Review the request data for validation errors
   • Check the debug logs for detailed error information
   • Verify the address information is correct

3. Gem installation issues

   • Ensure Ruby 3.2+ is installed
   • Run bundle update to update dependencies

Debug Mode

Enable debug logging in the settings menu to see detailed API communication logs.

License

This project uses the Apache-2.0 license, matching the Kintsugi SDK license.

Support

For issues with the Kintsugi API or SDK, please refer to the official Kintsugi documentation, or contact ryan.le@trykintsugi.com.