StateSet API Docs

StateSet provides official SDKs for popular languages to accelerate your integration development.

Official SDKs

Node.js / TypeScript

Full-featured SDK with TypeScript support

Python

Pythonic interface with async support

Go

High-performance SDK for Go applications

Ruby

Idiomatic Ruby SDK with Rails integration

PHP

Modern PHP SDK with PSR compliance

.NET / C#

.NET SDK with async/await support

Java

Enterprise-ready Java SDK

Swift

Native iOS/macOS SDK

Node.js / TypeScript

Installation

npm install @stateset/stateset-node

yarn add @stateset/stateset-node

pnpm add @stateset/stateset-node

Quick Start

import { StateSet } from '@stateset/stateset-node';

// Initialize client
const stateset = new StateSet({
  apiKey: process.env.STATESET_API_KEY,
  // Optional configuration
  environment: 'production', // or 'sandbox'
  timeout: 30000, // 30 seconds
  maxRetries: 3,
  apiVersion: '2024-01-01'
});

// TypeScript types are included
const order: StateSet.Order = await stateset.orders.create({
  customer: {
    email: 'customer@example.com',
    first_name: 'John',
    last_name: 'Doe'
  },
  items: [{
    sku: 'WIDGET-001',
    quantity: 2,
    price: 2999
  }],
  shipping_address: {
    line1: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    postal_code: '94105',
    country: 'US'
  }
});

Advanced Features

Async Iteration

// Iterate through all orders
for await (const order of stateset.orders.list()) {
  console.log(order.id);
}

// With filters
for await (const order of stateset.orders.list({ 
  status: 'pending' 
})) {
  await processOrder(order);
}

Request Interceptors

// Add request interceptor
stateset.interceptors.request.use((config) => {
  config.headers['X-Custom-Header'] = 'value';
  console.log(`Making request to ${config.url}`);
  return config;
});

// Add response interceptor
stateset.interceptors.response.use(
  (response) => {
    console.log(`Request completed in ${response.duration}ms`);
    return response;
  },
  (error) => {
    console.error('Request failed:', error);
    throw error;
  }
);

Event Emitters

// Listen for events
stateset.on('request', (event) => {
  console.log('Request:', event);
});

stateset.on('response', (event) => {
  console.log('Response:', event);
});

stateset.on('error', (error) => {
  console.error('Error:', error);
});

stateset.on('rateLimit', (info) => {
  console.warn('Rate limited:', info);
});

Custom HTTP Client

import axios from 'axios';

const stateset = new StateSet({
  apiKey: process.env.STATESET_API_KEY,
  httpClient: axios.create({
    timeout: 60000,
    proxy: {
      host: 'proxy.example.com',
      port: 8080
    }
  })
});

TypeScript Support

import { StateSet } from '@stateset/stateset-node';
import type { 
  Order,
  Customer,
  Return,
  OrderCreateParams,
  PaginatedResponse
} from '@stateset/stateset-node';

// Full type safety
async function createOrder(
  params: OrderCreateParams
): Promise<Order> {
  return await stateset.orders.create(params);
}

// Generic pagination
async function getAllOrders(): Promise<Order[]> {
  const response: PaginatedResponse<Order> = 
    await stateset.orders.list();
  return response.data;
}

// Type guards
function isOrder(obj: any): obj is Order {
  return obj && obj.object === 'order';
}

Python

Installation

pip install stateset-python

Quick Start

from stateset import StateSet
import os

# Initialize client
stateset = StateSet(
    api_key=os.getenv('STATESET_API_KEY'),
    # Optional configuration
    environment='production',  # or 'sandbox'
    timeout=30,  # seconds
    max_retries=3,
    api_version='2024-01-01'
)

# Create an order
order = stateset.orders.create(
    customer={
        'email': 'customer@example.com',
        'first_name': 'John',
        'last_name': 'Doe'
    },
    items=[{
        'sku': 'WIDGET-001',
        'quantity': 2,
        'price': 2999
    }],
    shipping_address={
        'line1': '123 Main St',
        'city': 'San Francisco',
        'state': 'CA',
        'postal_code': '94105',
        'country': 'US'
    }
)

Async Support

import asyncio
from stateset import AsyncStateSet

async def main():
    # Async client
    async with AsyncStateSet(api_key=api_key) as stateset:
        # Concurrent requests
        orders = await asyncio.gather(
            stateset.orders.get('ord_123'),
            stateset.orders.get('ord_456'),
            stateset.orders.get('ord_789')
        )
        
        # Async iteration
        async for order in stateset.orders.list_async():
            print(order.id)

asyncio.run(main())

Context Managers

from stateset import StateSet

# Automatic resource cleanup
with StateSet(api_key=api_key) as stateset:
    orders = stateset.orders.list()
    for order in orders:
        print(order.id)

Type Hints

from typing import List, Optional
from stateset import StateSet
from stateset.types import Order, Customer, OrderCreateParams

def create_order(
    stateset: StateSet,
    params: OrderCreateParams
) -> Order:
    """Create a new order with type safety."""
    return stateset.orders.create(**params)

def get_customer_orders(
    stateset: StateSet,
    customer_id: str,
    status: Optional[str] = None
) -> List[Order]:
    """Get all orders for a customer."""
    filters = {'customer_id': customer_id}
    if status:
        filters['status'] = status
    return list(stateset.orders.list(**filters))

Go

Installation

go get github.com/stateset/stateset-go

Quick Start

package main

import (
    "context"
    "fmt"
    "os"
    
    "github.com/stateset/stateset-go"
    "github.com/stateset/stateset-go/order"
)

func main() {
    // Initialize client
    client := stateset.NewClient(
        os.Getenv("STATESET_API_KEY"),
        &stateset.Config{
            Environment: stateset.Production,
            Timeout:     30 * time.Second,
            MaxRetries:  3,
        },
    )
    
    // Create an order
    params := &order.CreateParams{
        Customer: &order.CustomerParams{
            Email:     stateset.String("customer@example.com"),
            FirstName: stateset.String("John"),
            LastName:  stateset.String("Doe"),
        },
        Items: []*order.ItemParams{{
            SKU:      stateset.String("WIDGET-001"),
            Quantity: stateset.Int64(2),
            Price:    stateset.Int64(2999),
        }},
        ShippingAddress: &order.AddressParams{
            Line1:      stateset.String("123 Main St"),
            City:       stateset.String("San Francisco"),
            State:      stateset.String("CA"),
            PostalCode: stateset.String("94105"),
            Country:    stateset.String("US"),
        },
    }
    
    order, err := client.Orders.Create(context.Background(), params)
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Order created: %s\n", order.ID)
}

Error Handling

import (
    "errors"
    "github.com/stateset/stateset-go"
)

func handleOrder(client *stateset.Client, orderID string) error {
    order, err := client.Orders.Get(context.Background(), orderID)
    if err != nil {
        var statesetErr *stateset.Error
        if errors.As(err, &statesetErr) {
            switch statesetErr.Code {
            case stateset.ErrorCodeRateLimit:
                // Handle rate limiting
                time.Sleep(time.Duration(statesetErr.RetryAfter) * time.Second)
                return handleOrder(client, orderID) // Retry
            case stateset.ErrorCodeNotFound:
                // Handle not found
                return fmt.Errorf("order %s not found", orderID)
            default:
                return fmt.Errorf("API error: %v", statesetErr)
            }
        }
        return err
    }
    
    // Process order
    return nil
}

Concurrent Operations

func fetchOrdersConcurrently(client *stateset.Client, orderIDs []string) ([]*order.Order, error) {
    var wg sync.WaitGroup
    orders := make([]*order.Order, len(orderIDs))
    errors := make([]error, len(orderIDs))
    
    for i, id := range orderIDs {
        wg.Add(1)
        go func(index int, orderID string) {
            defer wg.Done()
            ord, err := client.Orders.Get(context.Background(), orderID)
            orders[index] = ord
            errors[index] = err
        }(i, id)
    }
    
    wg.Wait()
    
    // Check for errors
    for _, err := range errors {
        if err != nil {
            return nil, err
        }
    }
    
    return orders, nil
}

Ruby

Installation

# Gemfile
gem 'stateset-ruby'

bundle install
# or
gem install stateset-ruby

Quick Start

require 'stateset'

# Initialize client
Stateset.api_key = ENV['STATESET_API_KEY']

# Or configure globally
Stateset.configure do |config|
  config.api_key = ENV['STATESET_API_KEY']
  config.environment = :production # or :sandbox
  config.timeout = 30
  config.max_retries = 3
end

# Create an order
order = Stateset::Order.create(
  customer: {
    email: 'customer@example.com',
    first_name: 'John',
    last_name: 'Doe'
  },
  items: [{
    sku: 'WIDGET-001',
    quantity: 2,
    price: 2999
  }],
  shipping_address: {
    line1: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    postal_code: '94105',
    country: 'US'
  }
)

puts "Order created: #{order.id}"

Rails Integration

# config/initializers/stateset.rb
Stateset.configure do |config|
  config.api_key = Rails.application.credentials.stateset[:api_key]
  config.environment = Rails.env.production? ? :production : :sandbox
  config.logger = Rails.logger
end

# app/models/concerns/stateset_syncable.rb
module StatesetSyncable
  extend ActiveSupport::Concern
  
  included do
    after_create :sync_to_stateset
    after_update :update_in_stateset
  end
  
  def sync_to_stateset
    StatesetSyncJob.perform_later(self)
  end
  
  def update_in_stateset
    StatesetUpdateJob.perform_later(self)
  end
end

# app/models/order.rb
class Order < ApplicationRecord
  include StatesetSyncable
  
  def to_stateset_params
    {
      external_id: id,
      customer: {
        email: customer.email,
        first_name: customer.first_name,
        last_name: customer.last_name
      },
      items: items.map(&:to_stateset_params)
    }
  end
end

Error Handling

begin
  order = Stateset::Order.create(params)
rescue Stateset::RateLimitError => e
  # Handle rate limiting
  sleep(e.retry_after)
  retry
rescue Stateset::ValidationError => e
  # Handle validation errors
  e.errors.each do |error|
    puts "#{error.field}: #{error.message}"
  end
rescue Stateset::APIError => e
  # Handle other API errors
  puts "API Error: #{e.message}"
end

PHP

Installation

composer require stateset/stateset-php

Quick Start

<?php
require_once 'vendor/autoload.php';

use Stateset\StatesetClient;
use Stateset\Exception\ApiException;

// Initialize client
$stateset = new StatesetClient([
    'apiKey' => $_ENV['STATESET_API_KEY'],
    'environment' => 'production', // or 'sandbox'
    'timeout' => 30,
    'maxRetries' => 3
]);

// Create an order
try {
    $order = $stateset->orders->create([
        'customer' => [
            'email' => 'customer@example.com',
            'first_name' => 'John',
            'last_name' => 'Doe'
        ],
        'items' => [[
            'sku' => 'WIDGET-001',
            'quantity' => 2,
            'price' => 2999
        ]],
        'shipping_address' => [
            'line1' => '123 Main St',
            'city' => 'San Francisco',
            'state' => 'CA',
            'postal_code' => '94105',
            'country' => 'US'
        ]
    ]);
    
    echo "Order created: {$order->id}\n";
    
} catch (ApiException $e) {
    echo "Error: {$e->getMessage()}\n";
}

Laravel Integration

// config/stateset.php
return [
    'api_key' => env('STATESET_API_KEY'),
    'environment' => env('STATESET_ENVIRONMENT', 'production'),
    'timeout' => 30,
    'max_retries' => 3,
];

// app/Providers/StatesetServiceProvider.php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Stateset\StatesetClient;

class StatesetServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->singleton(StatesetClient::class, function ($app) {
            return new StatesetClient(config('stateset'));
        });
    }
}

// app/Services/OrderService.php
namespace App\Services;

use Stateset\StatesetClient;

class OrderService
{
    protected $stateset;
    
    public function __construct(StatesetClient $stateset)
    {
        $this->stateset = $stateset;
    }
    
    public function createOrder(array $data)
    {
        return $this->stateset->orders->create($data);
    }
}

.NET / C#

Installation

dotnet add package StateSet.Net

Quick Start

using StateSet;
using StateSet.Models;
using System;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        // Initialize client
        var client = new StateSetClient(
            Environment.GetEnvironmentVariable("STATESET_API_KEY"),
            new StateSetOptions
            {
                Environment = StateSetEnvironment.Production,
                Timeout = TimeSpan.FromSeconds(30),
                MaxRetries = 3
            }
        );
        
        // Create an order
        var order = await client.Orders.CreateAsync(new OrderCreateParams
        {
            Customer = new CustomerParams
            {
                Email = "customer@example.com",
                FirstName = "John",
                LastName = "Doe"
            },
            Items = new List<OrderItemParams>
            {
                new OrderItemParams
                {
                    Sku = "WIDGET-001",
                    Quantity = 2,
                    Price = 2999
                }
            },
            ShippingAddress = new AddressParams
            {
                Line1 = "123 Main St",
                City = "San Francisco",
                State = "CA",
                PostalCode = "94105",
                Country = "US"
            }
        });
        
        Console.WriteLine($"Order created: {order.Id}");
    }
}

Dependency Injection (ASP.NET Core)

// Startup.cs or Program.cs
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddStateSet(options =>
        {
            options.ApiKey = Configuration["StateSet:ApiKey"];
            options.Environment = StateSetEnvironment.Production;
        });
        
        services.AddScoped<IOrderService, OrderService>();
    }
}

// Services/OrderService.cs
public interface IOrderService
{
    Task<Order> CreateOrderAsync(OrderDto orderDto);
}

public class OrderService : IOrderService
{
    private readonly IStateSetClient _stateset;
    
    public OrderService(IStateSetClient stateset)
    {
        _stateset = stateset;
    }
    
    public async Task<Order> CreateOrderAsync(OrderDto orderDto)
    {
        return await _stateset.Orders.CreateAsync(orderDto.ToStateSetParams());
    }
}

Java

Installation

Maven

<dependency>
    <groupId>com.stateset</groupId>
    <artifactId>stateset-java</artifactId>
    <version>3.0.0</version>
</dependency>

Gradle

implementation 'com.stateset:stateset-java:3.0.0'

Quick Start

import com.stateset.StateSet;
import com.stateset.model.Order;
import com.stateset.param.OrderCreateParams;
import com.stateset.exception.StateSetException;

public class Main {
    public static void main(String[] args) {
        // Initialize client
        StateSet.apiKey = System.getenv("STATESET_API_KEY");
        
        // Or use builder
        StateSet stateset = StateSet.builder()
            .setApiKey(System.getenv("STATESET_API_KEY"))
            .setEnvironment(StateSet.Environment.PRODUCTION)
            .setTimeout(30000)
            .setMaxRetries(3)
            .build();
        
        try {
            // Create an order
            OrderCreateParams params = OrderCreateParams.builder()
                .setCustomer(
                    OrderCreateParams.Customer.builder()
                        .setEmail("customer@example.com")
                        .setFirstName("John")
                        .setLastName("Doe")
                        .build()
                )
                .addItem(
                    OrderCreateParams.Item.builder()
                        .setSku("WIDGET-001")
                        .setQuantity(2)
                        .setPrice(2999L)
                        .build()
                )
                .setShippingAddress(
                    OrderCreateParams.Address.builder()
                        .setLine1("123 Main St")
                        .setCity("San Francisco")
                        .setState("CA")
                        .setPostalCode("94105")
                        .setCountry("US")
                        .build()
                )
                .build();
            
            Order order = Order.create(params);
            System.out.println("Order created: " + order.getId());
            
        } catch (StateSetException e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Spring Boot Integration

// Configuration
@Configuration
public class StateSetConfig {
    
    @Value("${stateset.api-key}")
    private String apiKey;
    
    @Bean
    public StateSet statesetClient() {
        return StateSet.builder()
            .setApiKey(apiKey)
            .setEnvironment(StateSet.Environment.PRODUCTION)
            .build();
    }
}

// Service
@Service
public class OrderService {
    
    private final StateSet stateset;
    
    @Autowired
    public OrderService(StateSet stateset) {
        this.stateset = stateset;
    }
    
    public Order createOrder(OrderRequest request) throws StateSetException {
        OrderCreateParams params = convertToParams(request);
        return Order.create(params);
    }
}

Swift

Installation

Swift Package Manager

dependencies: [
    .package(url: "https://github.com/stateset/stateset-swift.git", from: "2.0.0")
]

CocoaPods

pod 'StateSet', '~> 2.0'

Quick Start

import StateSet

// Initialize client
let client = StateSetClient(
    apiKey: ProcessInfo.processInfo.environment["STATESET_API_KEY"]!,
    environment: .production,
    timeout: 30,
    maxRetries: 3
)

// Create an order
let customer = CustomerParams(
    email: "customer@example.com",
    firstName: "John",
    lastName: "Doe"
)

let item = OrderItemParams(
    sku: "WIDGET-001",
    quantity: 2,
    price: 2999
)

let address = AddressParams(
    line1: "123 Main St",
    city: "San Francisco",
    state: "CA",
    postalCode: "94105",
    country: "US"
)

let params = OrderCreateParams(
    customer: customer,
    items: [item],
    shippingAddress: address
)

client.orders.create(params) { result in
    switch result {
    case .success(let order):
        print("Order created: \(order.id)")
    case .failure(let error):
        print("Error: \(error.localizedDescription)")
    }
}

Async/Await Support

// iOS 13+, macOS 10.15+
@available(iOS 13.0, *)
func createOrder() async throws {
    let order = try await client.orders.create(params)
    print("Order created: \(order.id)")
}

// SwiftUI Integration
struct OrderView: View {
    @StateObject private var viewModel = OrderViewModel()
    
    var body: some View {
        Button("Create Order") {
            Task {
                await viewModel.createOrder()
            }
        }
    }
}

@MainActor
class OrderViewModel: ObservableObject {
    @Published var order: Order?
    @Published var isLoading = false
    @Published var error: Error?
    
    private let client = StateSetClient()
    
    func createOrder() async {
        isLoading = true
        do {
            order = try await client.orders.create(params)
        } catch {
            self.error = error
        }
        isLoading = false
    }
}

SDK Features Comparison

Feature	Node.js	Python	Go	Ruby	PHP	.NET	Java	Swift
Type Safety	✅ TypeScript	✅ Type Hints	✅	❌	❌	✅	✅	✅
Async/Await	✅	✅	✅	✅	❌	✅	✅ CompletableFuture	✅
Auto-Retry	✅	✅	✅	✅	✅	✅	✅	✅
Webhooks	✅	✅	✅	✅	✅	✅	✅	✅
Pagination	✅ Auto	✅ Auto	✅ Manual	✅ Auto	✅ Manual	✅ Auto	✅ Manual	✅ Auto
Streaming	✅	✅	✅	✅	❌	✅	✅	✅
Interceptors	✅	✅	✅	✅	❌	✅	✅	✅
File Upload	✅	✅	✅	✅	✅	✅	✅	✅
GraphQL	✅	✅	✅	✅	✅	✅	✅	✅

Common Patterns

Error Handling Across SDKs

All SDKs follow similar error handling patterns:

// JavaScript/TypeScript
try {
  const order = await stateset.orders.create(params);
} catch (error) {
  if (error.code === 'rate_limited') {
    // Handle rate limiting
  } else if (error.code === 'validation_error') {
    // Handle validation errors
  } else {
    // Handle other errors
  }
}

# Python
try:
    order = stateset.orders.create(**params)
except RateLimitError as e:
    # Handle rate limiting
    pass
except ValidationError as e:
    # Handle validation errors
    pass
except StateSetError as e:
    # Handle other errors
    pass

Idempotency Across SDKs

All SDKs support idempotency keys:

// JavaScript
const order = await stateset.orders.create(params, {
  idempotencyKey: 'unique-key-123'
});

# Python
order = stateset.orders.create(
    **params,
    idempotency_key='unique-key-123'
)

// Go
params.IdempotencyKey = stateset.String("unique-key-123")
order, err := client.Orders.Create(ctx, params)

Community SDKs

Community SDKs are not officially maintained by StateSet. Use at your own discretion.

Rust: stateset-rust
Kotlin: stateset-kotlin
Dart/Flutter: stateset-dart
Elixir: stateset-elixir
Clojure: stateset-clj

SDK Development

Contributing

We welcome contributions to our SDKs! See our SDK Development Guide for:

Code style guidelines
Testing requirements
Release process
API coverage requirements

Reporting Issues

Bug Reports: GitHub Issues
Feature Requests: Discord Community
Security Issues: security@stateset.com

API Reference - Complete API documentation
Quickstart Guide - Get started quickly
Authentication - Auth methods
Error Handling - Error codes and handling
Code Examples - Sample implementations

Need SDK support? Contact sdk-support@stateset.com or visit our Discord community.

​Official SDKs

Node.js / TypeScript

Python

Go

Ruby

PHP

.NET / C#

Java

Swift

​Node.js / TypeScript

​Installation

​Quick Start

​Advanced Features

​Async Iteration

​Request Interceptors

​Event Emitters

​Custom HTTP Client

​TypeScript Support

​Python

​Installation

​Quick Start

​Async Support

​Context Managers

​Type Hints

​Go

​Installation

​Quick Start

​Error Handling

​Concurrent Operations

​Ruby

​Installation

​Quick Start

​Rails Integration

​Error Handling

​PHP

​Installation

​Quick Start

​Laravel Integration

​.NET / C#

​Installation

​Quick Start

​Dependency Injection (ASP.NET Core)

​Java

​Installation

​Maven

​Gradle

​Quick Start

​Spring Boot Integration

​Swift

​Installation

​Swift Package Manager

​CocoaPods

​Quick Start

​Async/Await Support

​SDK Features Comparison

​Common Patterns

​Error Handling Across SDKs

​Idempotency Across SDKs

​Community SDKs

​SDK Development

​Contributing

​Reporting Issues

​Related Resources

Official SDKs

Node.js / TypeScript

Installation

Quick Start

Advanced Features

Async Iteration

Request Interceptors

Event Emitters

Custom HTTP Client

TypeScript Support

Python

Installation

Quick Start

Async Support

Context Managers

Type Hints

Go

Installation

Quick Start

Error Handling

Concurrent Operations

Ruby

Installation

Quick Start

Rails Integration

Error Handling

PHP

Installation

Quick Start

Laravel Integration

.NET / C#

Installation

Quick Start

Dependency Injection (ASP.NET Core)

Java

Installation

Maven

Gradle

Quick Start

Spring Boot Integration

Swift

Installation

Swift Package Manager

CocoaPods

Quick Start

Async/Await Support

SDK Features Comparison

Common Patterns

Error Handling Across SDKs

Idempotency Across SDKs

Community SDKs

SDK Development

Contributing

Reporting Issues

Related Resources