Skip to main content

SDK Examples

Real-world Integration Examples - These examples show how to integrate Kintsugi SDKs into common application patterns and frameworks.

E-commerce Integration

Shopify App Integration

  • Python
  • TypeScript
from kintsugi_tax import KintsugiClient
from shopify import ShopifyAPI

class TaxCalculator:
    def __init__(self, api_key, org_id):
        self.kintsugi = KintsugiClient(api_key, org_id)
    
    def calculate_cart_tax(self, cart_items, shipping_address):
        # Convert Shopify cart to Kintsugi format
        line_items = []
        for item in cart_items:
            line_items.append({
                "quantity": item.quantity,
                "price": float(item.price),
                "product_tax_code": item.product_tax_code or "A_GEN_TAX"
            })
        
        # Calculate tax
        tax_result = self.kintsugi.tax.estimate({
            "line_items": line_items,
            "ship_to": {
                "street_1": shipping_address.address1,
                "city": shipping_address.city,
                "state": shipping_address.province_code,
                "postal_code": shipping_address.zip,
                "country": shipping_address.country_code
            }
        })
        
        return {
            "total_tax": tax_result.total_tax,
            "tax_breakdown": tax_result.tax_breakdown
        }

Webhook Handling

Stripe Webhook Integration

  • Python
  • Node.js
from flask import Flask, request, jsonify
from kintsugi_tax import KintsugiClient
import stripe

app = Flask(__name__)
kintsugi = KintsugiClient(
    api_key=os.getenv("KINTSUGI_API_KEY"),
    organization_id=os.getenv("KINTSUGI_ORG_ID")
)

@app.route('/webhook/stripe', methods=['POST'])
def handle_stripe_webhook():
    payload = request.get_json()
    event_type = payload['type']
    
    if event_type == 'payment_intent.succeeded':
        payment_intent = payload['data']['object']
        
        # Calculate tax for the transaction
        tax_result = kintsugi.tax.estimate({
            "line_items": [{
                "quantity": 1,
                "price": payment_intent['amount'] / 100,
                "product_tax_code": "A_GEN_TAX"
            }],
            "ship_to": {
                "street_1": payment_intent['shipping']['address']['line1'],
                "city": payment_intent['shipping']['address']['city'],
                "state": payment_intent['shipping']['address']['state'],
                "postal_code": payment_intent['shipping']['address']['postal_code'],
                "country": payment_intent['shipping']['address']['country']
            }
        })
        
        # Store tax information
        store_tax_record(payment_intent['id'], tax_result)
        
    return jsonify({'status': 'success'})

Error Handling Patterns

Robust Error Handling

  • Python
  • TypeScript
from kintsugi_tax import KintsugiClient, KintsugiError
import logging

def calculate_tax_safely(client, transaction_data):
    try:
        result = client.tax.estimate(transaction_data)
        return result
    except KintsugiError as e:
        if e.status_code == 429:  # Rate limited
            logging.warning("Rate limited, retrying in 60 seconds")
            time.sleep(60)
            return client.tax.estimate(transaction_data)
        elif e.status_code == 400:  # Bad request
            logging.error(f"Invalid request: {e.message}")
            raise ValueError(f"Invalid transaction data: {e.message}")
        else:
            logging.error(f"Tax calculation failed: {e.message}")
            raise
    except Exception as e:
        logging.error(f"Unexpected error: {str(e)}")
        raise

Testing Patterns

Unit Testing with Mocks

  • Python
  • Jest
import unittest
from unittest.mock import Mock, patch
from kintsugi_tax import KintsugiClient

class TestTaxCalculation(unittest.TestCase):
    def setUp(self):
        self.client = KintsugiClient("test-key", "test-org")
    
    @patch('kintsugi.KintsugiClient.tax.estimate')
    def test_tax_calculation(self, mock_estimate):
        # Mock the response
        mock_estimate.return_value = {
            "total_tax": 8.25,
            "tax_breakdown": [{"jurisdiction": "CA", "tax": 8.25}]
        }
        
        # Test the calculation
        result = self.client.tax.estimate({
            "line_items": [{"quantity": 1, "price": 100}],
            "ship_to": {"state": "CA", "country": "US"}
        })
        
        self.assertEqual(result["total_tax"], 8.25)
        mock_estimate.assert_called_once()

Performance Optimization

Caching and Batching

  • Python
  • TypeScript
from functools import lru_cache
import redis

class CachedTaxCalculator:
    def __init__(self, api_key, org_id):
        self.kintsugi = KintsugiClient(api_key, org_id)
        self.redis = redis.Redis(host='localhost', port=6379, db=0)
    
    @lru_cache(maxsize=1000)
    def get_tax_rate(self, state, country):
        cache_key = f"tax_rate:{state}:{country}"
        cached_rate = self.redis.get(cache_key)
        
        if cached_rate:
            return float(cached_rate)
        
        # Calculate and cache
        result = self.kintsugi.tax.estimate({
            "line_items": [{"quantity": 1, "price": 100}],
            "ship_to": {"state": state, "country": country}
        })
        
        rate = result.total_tax / 100
        self.redis.setex(cache_key, 3600, rate)  # Cache for 1 hour
        return rate