Skip to main content

Java SDK

Official Java SDK - The Kintsugi Java SDK provides a robust, type-safe way to interact with the Kintsugi API from Java applications.

Installation

Maven

<dependency>
    <groupId>com.kintsugi.taxplatform</groupId>
    <artifactId>kintsugi-tax-java-sdk</artifactId>
    <version>0.14.0</version>
</dependency>

Gradle

implementation 'com.kintsugi.taxplatform:kintsugi-tax-java-sdk:0.14.0'

Quick Start

import com.kintsugi.taxplatform.SDK;
import com.kintsugi.taxplatform.models.operations.*;

public class Application {
    public static void main(String[] args) {
        // Initialize the SDK
        SDK sdk = SDK.builder()
            .apiKey("your-api-key")
            .organizationId("your-org-id")
            .build();

        // Calculate tax for a transaction
        TaxEstimateRequest request = TaxEstimateRequest.builder()
            .lineItems(Arrays.asList(
                LineItem.builder()
                    .quantity(1)
                    .price(100.00)
                    .productTaxCode("A_GEN_TAX")
                    .build()
            ))
            .shipTo(Address.builder()
                .street1("123 Main St")
                .city("San Francisco")
                .state("CA")
                .postalCode("94105")
                .country(CountryCodeEnum.US)
                .build())
            .build();

        try {
            TaxEstimateResponse response = sdk.tax().estimate(request);
            System.out.println("Tax amount: $" + response.getTotalTax());
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Repository

Java SDK Repository

View source code, report issues, and contribute to the Java SDK

Features

  • Type Safety: Full type safety with generated models
  • Builder Pattern: Fluent builder pattern for easy configuration
  • Error Handling: Comprehensive error handling with typed exceptions
  • Authentication: Simple API key authentication
  • Custom HTTP Client: Support for custom HTTP client configuration

Examples

Basic Tax Calculation

import com.kintsugi.taxplatform.SDK;
import com.kintsugi.taxplatform.models.operations.*;

public class TaxCalculator {
    private final SDK sdk;
    
    public TaxCalculator(String apiKey, String orgId) {
        this.sdk = SDK.builder()
            .apiKey(apiKey)
            .organizationId(orgId)
            .build();
    }
    
    public double calculateTax(List<LineItem> items, Address shipTo) {
        TaxEstimateRequest request = TaxEstimateRequest.builder()
            .lineItems(items)
            .shipTo(shipTo)
            .build();
        
        try {
            TaxEstimateResponse response = sdk.tax().estimate(request);
            return response.getTotalTax();
        } catch (Exception e) {
            throw new RuntimeException("Tax calculation failed", e);
        }
    }
}

Custom HTTP Client

import com.kintsugi.taxplatform.SDK;
import com.kintsugi.taxplatform.utils.HTTPClient;
import com.kintsugi.taxplatform.utils.SpeakeasyHTTPClient;

public class Application {
    public static void main(String[] args) {
        // Custom HTTP client with debug logging
        SpeakeasyHTTPClient httpClient = new SpeakeasyHTTPClient();
        httpClient.enableDebugLogging(true);
        
        SDK sdk = SDK.builder()
            .apiKey("your-api-key")
            .organizationId("your-org-id")
            .client(httpClient)
            .build();
    }
}

Error Handling

import com.kintsugi.taxplatform.SDK;
import com.kintsugi.taxplatform.models.errors.*;

public class Application {
    public static void main(String[] args) {
        SDK sdk = SDK.builder()
            .apiKey("your-api-key")
            .organizationId("your-org-id")
            .build();
        
        try {
            TaxEstimateResponse response = sdk.tax().estimate(request);
            // Handle success
        } catch (KintsugiError e) {
            if (e.getStatusCode() == 429) { // Rate limited
                System.out.println("Rate limited, retrying...");
                Thread.sleep(60000);
                response = sdk.tax().estimate(request);
            } else if (e.getStatusCode() == 400) { // Bad request
                System.err.println("Invalid request: " + e.getMessage());
            } else {
                System.err.println("API error: " + e.getMessage());
            }
        } catch (Exception e) {
            System.err.println("Unexpected error: " + e.getMessage());
        }
    }
}

Configuration

Environment Variables

export KINTSUGI_API_KEY="your-api-key"
export KINTSUGI_ORGANIZATION_ID="your-org-id"

Custom Configuration

import com.kintsugi.taxplatform.SDK;

SDK sdk = SDK.builder()
    .apiKey(System.getenv("KINTSUGI_API_KEY"))
    .organizationId(System.getenv("KINTSUGI_ORGANIZATION_ID"))
    .serverURL("https://api.trykintsugi.com") // Optional: custom base URL
    .timeout(Duration.ofSeconds(30)) // Optional: request timeout
    .build();

Testing

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.BeforeEach;
import org.mockito.Mock;
import org.mockito.MockitoAnnotations;
import static org.mockito.Mockito.*;
import static org.junit.jupiter.api.Assertions.*;

public class TaxCalculatorTest {
    @Mock
    private SDK mockSdk;
    
    @Mock
    private TaxService mockTaxService;
    
    private TaxCalculator calculator;
    
    @BeforeEach
    void setUp() {
        MockitoAnnotations.openMocks(this);
        when(mockSdk.tax()).thenReturn(mockTaxService);
        calculator = new TaxCalculator(mockSdk);
    }
    
    @Test
    void testTaxCalculation() {
        // Mock the response
        TaxEstimateResponse mockResponse = TaxEstimateResponse.builder()
            .totalTax(8.25)
            .build();
        
        when(mockTaxService.estimate(any(TaxEstimateRequest.class)))
            .thenReturn(mockResponse);
        
        // Test the calculation
        List<LineItem> items = Arrays.asList(
            LineItem.builder().quantity(1).price(100.0).build()
        );
        Address shipTo = Address.builder().state("CA").country(CountryCodeEnum.US).build();
        
        double result = calculator.calculateTax(items, shipTo);
        
        assertEquals(8.25, result);
        verify(mockTaxService).estimate(any(TaxEstimateRequest.class));
    }
}

Advanced Features

Custom HTTP Client with Hooks

import com.kintsugi.taxplatform.utils.HTTPClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.InputStream;

public class CustomHTTPClient implements HTTPClient {
    private final HTTPClient defaultClient = new SpeakeasyHTTPClient();
    
    @Override
    public HttpResponse<InputStream> send(HttpRequest request) throws Exception {
        // Add custom header
        HttpRequest modifiedRequest = HttpRequest.newBuilder(request)
            .header("x-custom-header", "custom value")
            .build();
        
        try {
            HttpResponse<InputStream> response = defaultClient.send(modifiedRequest);
            System.out.println("Request successful: " + response.statusCode());
            return response;
        } catch (Exception error) {
            System.err.println("Request failed: " + error.getMessage());
            throw error;
        }
    }
}

Support