# Install the main SDK
yarn add StateSet-node

# Install type definitions (if using TypeScript)
yarn add --dev @types/node

# Install recommended utilities
yarn add dotenv winston axios-retry

# Install the main SDK
pnpm add StateSet-node

# Install type definitions (if using TypeScript)
pnpm add --save-dev @types/node

# Install recommended utilities
pnpm add dotenv winston axios-retry

// app.ts
import { StateSetClient, StateSetConfig, StateSetError } from 'StateSet-node';
import dotenv from 'dotenv';

dotenv.config();

// Type-safe configuration
interface AppConfig {
  StateSet: StateSetConfig;
  app: {
    environment: 'development' | 'staging' | 'production';
    logLevel: 'debug' | 'info' | 'warn' | 'error';
  };
}

const config: AppConfig = {
  StateSet: {
    apiKey: process.env.STATESET_API_KEY!,
    environment: (process.env.STATESET_ENVIRONMENT as 'sandbox' | 'production') || 'sandbox',
    timeout: parseInt(process.env.STATESET_TIMEOUT || '30000'),
    maxRetries: parseInt(process.env.STATESET_MAX_RETRIES || '3'),
    telemetry: true
  },
  app: {
    environment: (process.env.NODE_ENV as any) || 'development',
    logLevel: (process.env.LOG_LEVEL as any) || 'info'
  }
};

const client = new StateSetClient(config.StateSet);

// Type-safe error handling
async function testConnection(): Promise<void> {
  try {
    const health = await client.health.check();
    logger.info('✅ Connected to StateSet:', health);
    
    // Test with proper types
    const { data: orders } = await client.orders.list({ 
      limit: 1,
      status: 'pending'
    });
    
    logger.info(`✅ Found ${orders.length} orders`);
    
  } catch (error) {
    if (error instanceof StateSetError) {
      logger.error('StateSet API Error:', {
        message: error.message,
        code: error.code,
        statusCode: error.statusCode,
        requestId: error.requestId
      });
    } else {
      logger.error('Unexpected error:', error);
    }
    process.exit(1);
  }
}

testConnection();

// app.js
const { StateSetClient } = require('StateSet-node');
require('dotenv').config();

// Create client with error handling
let client;
try {
  client = new StateSetClient({
    apiKey: process.env.STATESET_API_KEY,
    environment: process.env.STATESET_ENVIRONMENT || 'sandbox',
    timeout: 30000,
    maxRetries: 3
  });
} catch (error) {
  logger.error('Failed to initialize StateSet client:', error.message);
  process.exit(1);
}

// Test the connection
client.health.check()
  .then(health => {
    logger.info('✅ Connected to StateSet:', health.status);
    return client.orders.list({ limit: 1 });
  })
  .then(({ data: orders }) => {
    logger.info('✅ API Access verified:', orders.length, 'orders found');
  })
  .catch(error => {
    logger.error('❌ Connection failed:', error.message);
    process.exit(1);
  });

import { StateSetClient } from 'StateSet-node';
import { HttpsProxyAgent } from 'https-proxy-agent';

const proxyAgent = new HttpsProxyAgent('http://proxy.company.com:8080');

const client = new StateSetClient({
  apiKey: process.env.STATESET_API_KEY,
  httpAgent: proxyAgent,
  httpsAgent: proxyAgent
});

import { StateSetClient } from 'StateSet-node';
import winston from 'winston';

// Create Winston logger
const logger = winston.createLogger({
  level: process.env.LOG_LEVEL || 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  transports: [
    new winston.transports.Console({
      format: winston.format.simple()
    }),
    new winston.transports.File({ 
      filename: 'StateSet-errors.log', 
      level: 'error' 
    })
  ]
});

const client = new StateSetClient({
  apiKey: process.env.STATESET_API_KEY,
  logger: logger
});

// lib/StateSet.ts
import { StateSetClient } from 'StateSet-node';

// Singleton pattern for client-side usage
let client: StateSetClient;

export function getStateSetClient() {
  if (!client) {
    client = new StateSetClient({
      apiKey: process.env.STATESET_API_KEY!,
      environment: process.env.NEXT_PUBLIC_STATESET_ENV as 'sandbox' | 'production' || 'sandbox'
    });
  }
  return client;
}

// Server-side client (for API routes)
export const serverClient = new StateSetClient({
  apiKey: process.env.STATESET_API_KEY!,
  environment: process.env.STATESET_ENVIRONMENT as 'sandbox' | 'production' || 'sandbox'
});

// Type-safe API wrapper
export async function apiWrapper<T>(
  apiCall: () => Promise<T>
): Promise<{ data?: T; error?: string }> {
  try {
    const data = await apiCall();
    return { data };
  } catch (error: any) {
    logger.error('StateSet API Error:', error);
    return { 
      error: error.message || 'An unexpected error occurred' 
    };
  }
}

// pages/api/orders/index.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { serverClient, apiWrapper } from '../../../lib/StateSet';

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  // Enable CORS if needed
  res.setHeader('Access-Control-Allow-Origin', '*');
  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
  
  if (req.method === 'OPTIONS') {
    return res.status(200).end();
  }
  
  switch (req.method) {
    case 'GET': {
      const { page = '1', limit = '20', status } = req.query;
      
      const result = await apiWrapper(() => 
        serverClient.orders.list({
          page: parseInt(page as string),
          limit: parseInt(limit as string),
          status: status as string
        })
      );
      
      if (result.error) {
        return res.status(400).json({ error: result.error });
      }
      
      return res.status(200).json(result.data);
    }
    
    case 'POST': {
      const result = await apiWrapper(() => 
        serverClient.orders.create(req.body)
      );
      
      if (result.error) {
        return res.status(400).json({ error: result.error });
      }
      
      return res.status(201).json(result.data);
    }
    
    default:
      res.setHeader('Allow', ['GET', 'POST']);
      return res.status(405).json({ 
        error: `Method ${req.method} Not Allowed` 
      });
  }
}

// hooks/useStateSet.ts (React Hook)
import { useState, useEffect } from 'react';
import { getStateSetClient } from '../lib/StateSet';

export function useOrders(options = {}) {
  const [orders, setOrders] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  
  useEffect(() => {
    const fetchOrders = async () => {
      try {
        const client = getStateSetClient();
        const { data } = await client.orders.list(options);
        setOrders(data);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    };
    
    fetchOrders();
  }, []);
  
  return { orders, loading, error };
}

// StateSet/StateSet.module.ts
import { Module, DynamicModule, Global } from '@nestjs/common';
import { StateSetClient } from 'StateSet-node';
import { STATESET_CLIENT } from './StateSet.constants';
import { StateSetService } from './StateSet.service';

export interface StateSetModuleOptions {
  apiKey: string;
  environment?: 'sandbox' | 'production';
  isGlobal?: boolean;
}

@Module({})
export class StateSetModule {
  static forRoot(options: StateSetModuleOptions): DynamicModule {
    const providers = [
      {
        provide: STATESET_CLIENT,
        useFactory: () => new StateSetClient({
          apiKey: options.apiKey,
          environment: options.environment || 'sandbox'
        })
      },
      StateSetService
    ];
    
    return {
      module: StateSetModule,
      global: options.isGlobal ?? true,
      providers,
      exports: [STATESET_CLIENT, StateSetService]
    };
  }
  
  static forRootAsync(options: {
    useFactory: (...args: any[]) => Promise<StateSetModuleOptions> | StateSetModuleOptions;
    inject?: any[];
    isGlobal?: boolean;
  }): DynamicModule {
    const providers = [
      {
        provide: STATESET_CLIENT,
        useFactory: async (...args: any[]) => {
          const config = await options.useFactory(...args);
          return new StateSetClient({
            apiKey: config.apiKey,
            environment: config.environment || 'sandbox'
          });
        },
        inject: options.inject || []
      },
      StateSetService
    ];
    
    return {
      module: StateSetModule,
      global: options.isGlobal ?? true,
      providers,
      exports: [STATESET_CLIENT, StateSetService]
    };
  }
}

// StateSet/StateSet.service.ts
import { Injectable, Inject, Logger } from '@nestjs/common';
import { StateSetClient } from 'StateSet-node';
import { STATESET_CLIENT } from './StateSet.constants';

@Injectable()
export class StateSetService {
  private readonly logger = new Logger(StateSetService.name);
  
  constructor(
    @Inject(STATESET_CLIENT) private readonly client: StateSetClient
  ) {}
  
  async createOrder(data: any) {
    try {
      this.logger.log('Creating order', { customerId: data.customer_id });
      const order = await this.client.orders.create(data);
      this.logger.log('Order created successfully', { orderId: order.id });
      return order;
    } catch (error) {
      this.logger.error('Failed to create order', error);
      throw error;
    }
  }
  
  async getOrders(filters = {}) {
    return this.client.orders.list(filters);
  }
  
  async getOrder(id: string) {
    return this.client.orders.retrieve(id);
  }
  
  async updateOrder(id: string, data: any) {
    return this.client.orders.update(id, data);
  }
}

// app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { StateSetModule } from './StateSet/StateSet.module';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true
    }),
    StateSetModule.forRootAsync({
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        apiKey: config.get('STATESET_API_KEY'),
        environment: config.get('STATESET_ENVIRONMENT', 'sandbox')
      })
    })
  ]
})
export class AppModule {}

// orders/orders.controller.ts
import { 
  Controller, 
  Get, 
  Post, 
  Body, 
  Param, 
  Query,
  UseInterceptors,
  ClassSerializerInterceptor
} from '@nestjs/common';
import { StateSetService } from '../StateSet/StateSet.service';

@Controller('orders')
@UseInterceptors(ClassSerializerInterceptor)
export class OrdersController {
  constructor(private readonly StateSetService: StateSetService) {}
  
  @Get()
  async getOrders(
    @Query('page') page = 1,
    @Query('limit') limit = 20,
    @Query('status') status?: string
  ) {
    return this.StateSetService.getOrders({
      page: Number(page),
      limit: Number(limit),
      status
    });
  }
  
  @Get(':id')
  async getOrder(@Param('id') id: string) {
    return this.StateSetService.getOrder(id);
  }
  
  @Post()
  async createOrder(@Body() createOrderDto: any) {
    return this.StateSetService.createOrder(createOrderDto);
  }
}

# Add StateSet SDK
poetry add StateSet-python

# Add with extras
poetry add "StateSet-python[async,pandas]"

# Add development dependencies
poetry add --group dev pytest pytest-asyncio black mypy

# Install via pip in conda environment
pip install StateSet-python

# Install conda dependencies first
conda install pandas numpy requests
pip install "StateSet-python[async]"

# requirements.txt
StateSet-python>=2.0.0
python-dotenv>=0.19.0
requests>=2.28.0

# Optional: async support
httpx>=0.23.0

# Optional: data analysis
pandas>=1.3.0
numpy>=1.21.0

pip install -r requirements.txt

# app_async.py
import asyncio
from src.config.StateSet import async_client, Config, logger

async def test_connection():
    """Test StateSet async connection"""
    try:
        # Test health check
        health = await async_client.health.check()
        logger.info(f"✅ Connected to StateSet: {health}")
        
        # Test parallel API calls
        tasks = [
            async_client.orders.list(limit=5),
            async_client.customers.list(limit=5),
            async_client.products.list(limit=5)
        ]
        
        results = await asyncio.gather(*tasks, return_exceptions=True)
        
        for i, result in enumerate(results):
            if isinstance(result, Exception):
                logger.error(f"Task {i} failed: {result}")
            else:
                logger.info(f"Task {i} succeeded: {len(result.data)} items")
        
        return True
        
    except Exception as e:
        logger.error(f"❌ Connection failed: {str(e)}")
        return False
    finally:
        await async_client.close()

if __name__ == "__main__":
    asyncio.run(test_connection())

# app_typed.py
from typing import List, Optional, Dict, Any
from dataclasses import dataclass
from src.config.StateSet import client, logger
from StateSet.models import Order, Customer, Product

@dataclass
class OrderService:
    """Type-safe order service"""
    client: Any
    
    def get_orders(
        self, 
        status: Optional[str] = None,
        limit: int = 20
    ) -> List[Order]:
        """Get orders with optional filtering"""
        try:
            response = self.client.orders.list(
                status=status,
                limit=limit
            )
            return response.data
        except Exception as e:
            logger.error(f"Failed to fetch orders: {e}")
            raise
    
    def create_order(self, order_data: Dict[str, Any]) -> Order:
        """Create a new order"""
        try:
            return self.client.orders.create(**order_data)
        except Exception as e:
            logger.error(f"Failed to create order: {e}")
            raise
    
    def get_order_summary(self, order_id: str) -> Dict[str, Any]:
        """Get comprehensive order summary"""
        order = self.client.orders.retrieve(order_id)
        customer = self.client.customers.retrieve(order.customer_id)
        
        return {
            "order": order,
            "customer": customer,
            "total_amount": order.total,
            "status": order.status
        }

# Usage
service = OrderService(client=client)
orders = service.get_orders(status="pending", limit=10)
print(f"Found {len(orders)} pending orders")

# main.py
from fastapi import FastAPI, HTTPException, Query, Depends
from fastapi.responses import JSONResponse
from pydantic import BaseModel, Field
from typing import Optional, List, Dict, Any
from src.config.StateSet import async_client, Config, logger
import uvicorn

app = FastAPI(title="StateSet API", version="1.0.0")

# Pydantic models
class OrderCreate(BaseModel):
    customer_id: str
    items: List[Dict[str, Any]]
    shipping_address: Dict[str, str]
    metadata: Optional[Dict[str, Any]] = None

class OrderResponse(BaseModel):
    id: str
    customer_id: str
    status: str
    total: float
    created_at: str

class PaginatedResponse(BaseModel):
    data: List[Any]
    pagination: Dict[str, int]

# Dependency for StateSet client
async def get_StateSet_client():
    return async_client

# Exception handler
@app.exception_handler(Exception)
async def StateSet_exception_handler(request, exc):
    logger.error(f"StateSet error: {exc}")
    
    if hasattr(exc, 'status_code'):
        status_code = exc.status_code
    else:
        status_code = 500
    
    return JSONResponse(
        status_code=status_code,
        content={
            "detail": str(exc),
            "type": type(exc).__name__
        }
    )

# Routes
@app.get("/api/orders", response_model=PaginatedResponse)
async def get_orders(
    page: int = Query(1, ge=1),
    limit: int = Query(20, ge=1, le=100),
    status: Optional[str] = None,
    client = Depends(get_StateSet_client)
):
    """Get paginated list of orders"""
    response = await client.orders.list(
        page=page,
        limit=limit,
        status=status
    )
    
    return {
        "data": response.data,
        "pagination": {
            "page": response.page,
            "limit": response.limit,
            "total": response.total
        }
    }

@app.post("/api/orders", response_model=OrderResponse, status_code=201)
async def create_order(
    order: OrderCreate,
    client = Depends(get_StateSet_client)
):
    """Create a new order"""
    result = await client.orders.create(**order.dict())
    return result

@app.get("/api/orders/{order_id}", response_model=OrderResponse)
async def get_order(
    order_id: str,
    client = Depends(get_StateSet_client)
):
    """Get order by ID"""
    order = await client.orders.retrieve(order_id)
    if not order:
        raise HTTPException(status_code=404, detail="Order not found")
    return order

@app.get("/api/health")
async def health_check(client = Depends(get_StateSet_client)):
    """Health check endpoint"""
    try:
        health = await client.health.check()
        return {
            "status": "healthy",
            "StateSet": health,
            "environment": Config.ENVIRONMENT
        }
    except Exception as e:
        raise HTTPException(status_code=503, detail=str(e))

# Startup/shutdown events
@app.on_event("startup")
async def startup_event():
    logger.info("Starting up StateSet FastAPI app")

@app.on_event("shutdown")
async def shutdown_event():
    logger.info("Shutting down StateSet FastAPI app")
    await async_client.close()

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

# settings.py
import os
from dotenv import load_dotenv

load_dotenv()

# StateSet Configuration
STATESET_API_KEY = os.getenv('STATESET_API_KEY')
STATESET_ENVIRONMENT = os.getenv('STATESET_ENVIRONMENT', 'sandbox')
STATESET_WEBHOOK_SECRET = os.getenv('STATESET_WEBHOOK_SECRET')

# StateSet_client.py
from django.conf import settings
from StateSet import StateSetClient
import logging

logger = logging.getLogger(__name__)

class StateSetService:
    """Singleton StateSet service for Django"""
    _instance = None
    _client = None
    
    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance
    
    @property
    def client(self):
        if self._client is None:
            self._client = StateSetClient(
                api_key=settings.STATESET_API_KEY,
                environment=settings.STATESET_ENVIRONMENT
            )
        return self._client

# views.py
from django.http import JsonResponse
from django.views import View
from django.views.decorators.csrf import csrf_exempt
from django.utils.decorators import method_decorator
from .StateSet_client import StateSetService
import json

StateSet_service = StateSetService()

@method_decorator(csrf_exempt, name='dispatch')
class OrdersView(View):
    def get(self, request):
        try:
            page = int(request.GET.get('page', 1))
            limit = int(request.GET.get('limit', 20))
            status = request.GET.get('status')
            
            response = StateSet_service.client.orders.list(
                page=page,
                limit=limit,
                status=status
            )
            
            return JsonResponse({
                'success': True,
                'data': response.data,
                'pagination': {
                    'page': response.page,
                    'limit': response.limit,
                    'total': response.total
                }
            })
        except Exception as e:
            return JsonResponse({
                'success': False,
                'error': str(e)
            }, status=500)
    
    def post(self, request):
        try:
            data = json.loads(request.body)
            order = StateSet_service.client.orders.create(**data)
            
            return JsonResponse({
                'success': True,
                'data': order
            }, status=201)
        except Exception as e:
            return JsonResponse({
                'success': False,
                'error': str(e)
            }, status=400)

class OrderDetailView(View):
    def get(self, request, order_id):
        try:
            order = StateSet_service.client.orders.retrieve(order_id)
            return JsonResponse({
                'success': True,
                'data': order
            })
        except Exception as e:
            status_code = 404 if 'not found' in str(e).lower() else 500
            return JsonResponse({
                'success': False,
                'error': str(e)
            }, status=status_code)

# urls.py
from django.urls import path
from .views import OrdersView, OrderDetailView

urlpatterns = [
    path('api/orders/', OrdersView.as_view(), name='orders'),
    path('api/orders/<str:order_id>/', OrderDetailView.as_view(), name='order-detail'),
]

# Install directly via gem
gem install StateSet-ruby

# Install with specific version
gem install StateSet-ruby -v '2.0.0'

# Install development version
gem install StateSet-ruby --pre

# Clone and build from source
git clone https://github.com/StateSet/StateSet-ruby.git
cd StateSet-ruby
bundle install
rake build
gem install pkg/StateSet-ruby-*.gem