SDK Installation & Setup Guide

This comprehensive guide covers installing and configuring StateSet SDKs across different programming languages, package managers, and development environments.

Supported SDKs

StateSet provides official SDKs for the following languages:

Node.js / TypeScript

Most popular SDK with full TypeScript support

Python

Comprehensive Python SDK for backend applications

Ruby

Ruby SDK for Rails and Sinatra applications

PHP

PHP SDK for WordPress and Laravel projects

Node.js SDK

Prerequisites

Runtime Requirements

Node.js: Version 16.0.0 or higher
npm: Version 7.0.0 or higher (or yarn/pnpm)
TypeScript: Version 4.5+ (optional but recommended)

Environment Setup

Modern terminal with UTF-8 support
Text editor with JavaScript/TypeScript support
Git for version control

Installation

# Install the main SDK
npm install stateset-node

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

# Install additional utilities (optional)
npm install dotenv winston

# Install the main SDK
npm install stateset-node

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

# Install additional utilities (optional)
npm install dotenv winston

# Install the main SDK
yarn add stateset-node

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

# Install additional utilities (optional)
yarn add dotenv winston

# Install the main SDK
pnpm add stateset-node

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

# Install additional utilities (optional)
pnpm add dotenv winston

Quick Setup

Create a new project and configure the SDK:

# Create a new project
mkdir my-stateset-app
cd my-stateset-app

# Initialize package.json
npm init -y

# Install StateSet SDK
npm install stateset-node dotenv

# Create environment file
touch .env

Add your API credentials to .env:

# .env
STATESET_API_KEY=sk_live_51H9x2C2QlDjKpM2WYw5...
STATESET_ENVIRONMENT=production
STATESET_WEBHOOK_SECRET=whsec_3rK9pL7nQ2xS5mT8...

Basic Configuration

// app.js
import { StateSetClient } from 'stateset-node';
import dotenv from 'dotenv';

dotenv.config();

const client = new StateSetClient({
  apiKey: process.env.STATESET_API_KEY,
  environment: process.env.STATESET_ENVIRONMENT || 'sandbox',
  timeout: 30000,
  maxRetries: 3
});

// Test the connection
async function testConnection() {
  try {
    const health = await client.health.check();
    console.log('✅ Connected to StateSet:', health.status);
  } catch (error) {
    console.error('❌ Connection failed:', error.message);
  }
}

testConnection();

// app.js
import { StateSetClient } from 'stateset-node';
import dotenv from 'dotenv';

dotenv.config();

const client = new StateSetClient({
  apiKey: process.env.STATESET_API_KEY,
  environment: process.env.STATESET_ENVIRONMENT || 'sandbox',
  timeout: 30000,
  maxRetries: 3
});

// Test the connection
async function testConnection() {
  try {
    const health = await client.health.check();
    console.log('✅ Connected to StateSet:', health.status);
  } catch (error) {
    console.error('❌ Connection failed:', error.message);
  }
}

testConnection();

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

dotenv.config();

const config: StateSetConfig = {
  apiKey: process.env.STATESET_API_KEY!,
  environment: (process.env.STATESET_ENVIRONMENT as 'sandbox' | 'production') || 'sandbox',
  timeout: 30000,
  maxRetries: 3
};

const client = new StateSetClient(config);

// Test the connection with proper typing
async function testConnection(): Promise<void> {
  try {
    const health = await client.health.check();
    console.log('✅ Connected to StateSet:', health.status);
  } catch (error: any) {
    console.error('❌ Connection failed:', error.message);
  }
}

testConnection();

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

const client = new StateSetClient({
  apiKey: process.env.STATESET_API_KEY,
  environment: process.env.STATESET_ENVIRONMENT || 'sandbox',
  timeout: 30000,
  maxRetries: 3
});

// Test the connection
client.health.check()
  .then(health => {
    console.log('✅ Connected to StateSet:', health.status);
  })
  .catch(error => {
    console.error('❌ Connection failed:', error.message);
  });

Framework Integration

import express from 'express';
import { StateSetClient } from 'stateset-node';

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

// Middleware to add StateSet client to request
app.use((req, res, next) => {
  req.stateset = client;
  next();
});

app.get('/orders', async (req, res) => {
  try {
    const orders = await req.stateset.orders.list();
    res.json(orders);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

import express from 'express';
import { StateSetClient } from 'stateset-node';

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

// Middleware to add StateSet client to request
app.use((req, res, next) => {
  req.stateset = client;
  next();
});

app.get('/orders', async (req, res) => {
  try {
    const orders = await req.stateset.orders.list();
    res.json(orders);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

// lib/stateset.js
import { StateSetClient } from 'stateset-node';

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

export default client;

// pages/api/orders.js
import client from '../../lib/stateset';

export default async function handler(req, res) {
  try {
    const orders = await client.orders.list();
    res.status(200).json(orders);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
}

// stateset.module.ts
import { Module } from '@nestjs/common';
import { StateSetClient } from 'stateset-node';

@Module({
  providers: [
    {
      provide: 'STATESET_CLIENT',
      useFactory: () => new StateSetClient({
        apiKey: process.env.STATESET_API_KEY
      })
    }
  ],
  exports: ['STATESET_CLIENT']
})
export class StateSetModule {}

// orders.service.ts
import { Injectable, Inject } from '@nestjs/common';
import { StateSetClient } from 'stateset-node';

@Injectable()
export class OrdersService {
  constructor(
    @Inject('STATESET_CLIENT') private readonly client: StateSetClient
  ) {}

  async getOrders() {
    return this.client.orders.list();
  }
}

Python SDK

Prerequisites

Python Requirements

Python: Version 3.8 or higher
pip: Latest version recommended
Virtual environment: venv, conda, or poetry

Development Tools

Code editor with Python support
Git for version control
Terminal access

Installation

# Create virtual environment
python -m venv stateset-env
source stateset-env/bin/activate  # On Windows: stateset-env\Scripts\activate

# Install StateSet SDK
pip install stateset-python

# Install optional dependencies
pip install python-dotenv requests

# Create virtual environment
python -m venv stateset-env
source stateset-env/bin/activate  # On Windows: stateset-env\Scripts\activate

# Install StateSet SDK
pip install stateset-python

# Install optional dependencies
pip install python-dotenv requests

# Initialize new project
poetry new my-stateset-app
cd my-stateset-app

# Add StateSet SDK
poetry add stateset-python

# Add development dependencies
poetry add --group dev python-dotenv pytest

# Create conda environment
conda create -n stateset-env python=3.9
conda activate stateset-env

# Install via pip (StateSet not yet in conda-forge)
pip install stateset-python python-dotenv

Basic Configuration

# app.py
import os
from stateset import StateSetClient
from dotenv import load_dotenv

load_dotenv()

client = StateSetClient(
    api_key=os.getenv('STATESET_API_KEY'),
    environment=os.getenv('STATESET_ENVIRONMENT', 'sandbox'),
    timeout=30,
    max_retries=3
)

# Test the connection
def test_connection():
    try:
        health = client.health.check()
        print(f"✅ Connected to StateSet: {health['status']}")
    except Exception as error:
        print(f"❌ Connection failed: {str(error)}")

if __name__ == "__main__":
    test_connection()

Framework Integration

from flask import Flask, jsonify, request
from stateset import StateSetClient
import os

app = Flask(__name__)
client = StateSetClient(api_key=os.getenv('STATESET_API_KEY'))

@app.route('/orders')
def get_orders():
    try:
        orders = client.orders.list()
        return jsonify(orders)
    except Exception as e:
        return jsonify({'error': str(e)}), 500

if __name__ == '__main__':
    app.run(debug=True)

from flask import Flask, jsonify, request
from stateset import StateSetClient
import os

app = Flask(__name__)
client = StateSetClient(api_key=os.getenv('STATESET_API_KEY'))

@app.route('/orders')
def get_orders():
    try:
        orders = client.orders.list()
        return jsonify(orders)
    except Exception as e:
        return jsonify({'error': str(e)}), 500

if __name__ == '__main__':
    app.run(debug=True)

from fastapi import FastAPI, HTTPException
from stateset import StateSetClient
import os

app = FastAPI()
client = StateSetClient(api_key=os.getenv('STATESET_API_KEY'))

@app.get("/orders")
async def get_orders():
    try:
        orders = await client.orders.list()
        return orders
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

# settings.py
STATESET_API_KEY = os.getenv('STATESET_API_KEY')

# views.py
from django.http import JsonResponse
from stateset import StateSetClient
from django.conf import settings

client = StateSetClient(api_key=settings.STATESET_API_KEY)

def orders_view(request):
    try:
        orders = client.orders.list()
        return JsonResponse(orders, safe=False)
    except Exception as e:
        return JsonResponse({'error': str(e)}, status=500)

Ruby SDK

Prerequisites

Ruby: Version 2.7 or higher
Bundler: For dependency management
RubyGems: Latest version

Installation

# Gemfile
gem 'stateset-ruby'
gem 'dotenv-rails' # For Rails apps
# or
gem 'dotenv' # For non-Rails apps

bundle install

Basic Configuration

# config/initializers/stateset.rb (Rails)
# or app.rb (Sinatra/plain Ruby)

require 'stateset'
require 'dotenv/load'

Stateset.configure do |config|
  config.api_key = ENV['STATESET_API_KEY']
  config.environment = ENV['STATESET_ENVIRONMENT'] || 'sandbox'
  config.timeout = 30
end

# Test connection
begin
  health = Stateset::Health.check
  puts "✅ Connected to StateSet: #{health['status']}"
rescue => e
  puts "❌ Connection failed: #{e.message}"
end

PHP SDK

Prerequisites

PHP: Version 8.0 or higher
Composer: For dependency management
curl extension: Enabled

Installation

composer require stateset/stateset-php

Basic Configuration

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

use Stateset\StateSetClient;

$client = new StateSetClient([
    'api_key' => $_ENV['STATESET_API_KEY'],
    'environment' => $_ENV['STATESET_ENVIRONMENT'] ?? 'sandbox',
    'timeout' => 30
]);

// Test connection
try {
    $health = $client->health->check();
    echo "✅ Connected to StateSet: " . $health['status'] . "\n";
} catch (Exception $e) {
    echo "❌ Connection failed: " . $e->getMessage() . "\n";
}
?>

Environment Configuration

Development Environment

# .env.development
STATESET_API_KEY=sk_test_51H9x2C2QlDjKpM2WYw5...
STATESET_ENVIRONMENT=sandbox
STATESET_WEBHOOK_SECRET=whsec_test_3rK9pL7nQ2xS5mT8...
LOG_LEVEL=debug

Production Environment

# .env.production
STATESET_API_KEY=sk_live_51H9x2C2QlDjKpM2WYw5...
STATESET_ENVIRONMENT=production
STATESET_WEBHOOK_SECRET=whsec_prod_3rK9pL7nQ2xS5mT8...
LOG_LEVEL=info

Docker Configuration

# Dockerfile
FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .

EXPOSE 3000

CMD ["npm", "start"]

# docker-compose.yml
version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - STATESET_API_KEY=${STATESET_API_KEY}
      - STATESET_ENVIRONMENT=production
    volumes:
      - .:/app
      - /app/node_modules

Troubleshooting

Common Issues

Authentication Errors

Network Timeouts

Module Import Errors

Debug Mode

Enable debug logging to troubleshoot issues:

const client = new StateSetClient({
  apiKey: process.env.STATESET_API_KEY,
  debug: true,
  logLevel: 'debug'
});

const client = new StateSetClient({
  apiKey: process.env.STATESET_API_KEY,
  debug: true,
  logLevel: 'debug'
});

import logging
logging.basicConfig(level=logging.DEBUG)

client = StateSetClient(
    api_key=os.getenv('STATESET_API_KEY'),
    debug=True
)

Health Check Script

Create a health check script to verify your setup:

// health-check.js
import { StateSetClient } from 'stateset-node';

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

async function runHealthCheck() {
  const checks = [
    { name: 'API Connection', test: () => client.health.check() },
    { name: 'Orders API', test: () => client.orders.list({ limit: 1 }) },
    { name: 'Customers API', test: () => client.customers.list({ limit: 1 }) }
  ];

  for (const check of checks) {
    try {
      await check.test();
      console.log(`✅ ${check.name}: OK`);
    } catch (error) {
      console.error(`❌ ${check.name}: ${error.message}`);
    }
  }
}

runHealthCheck();

Next Steps

After installing the SDK:

Follow a Quickstart Guide: Choose a quickstart guide based on your use case
Explore API Reference: Review the API documentation for detailed endpoint information
Set Up Webhooks: Configure webhook security for real-time updates
Implement Error Handling: Follow error handling best practices

Support

If you encounter issues during installation:

📚 Check our troubleshooting guide
💬 Join our Discord community
📧 Contact support: support@stateset.com

Introduction to StateSet Developer Guide

On this page

SDK Installation & Setup Guide
Supported SDKs
Node.js SDK
Prerequisites
Installation
Quick Setup
Basic Configuration
Framework Integration
Python SDK
Prerequisites
Installation
Basic Configuration
Framework Integration
Ruby SDK
Prerequisites
Installation
Basic Configuration
PHP SDK
Prerequisites
Installation
Basic Configuration
Environment Configuration
Development Environment
Production Environment
Docker Configuration
Troubleshooting
Common Issues
Debug Mode
Health Check Script
Next Steps
Support

Get Started

StateSet One Guides

StateSet ResponseCX Guides

StateSet Commerce Network Guides

StateSet ReSponse API Documentation

​SDK Installation & Setup Guide

​Supported SDKs

Node.js / TypeScript

Python

Ruby

PHP

​Node.js SDK

​Prerequisites

Runtime Requirements

Environment Setup

​Installation

​Quick Setup

​Basic Configuration

​Framework Integration

​Python SDK

​Prerequisites

Python Requirements

Development Tools

​Installation

​Basic Configuration

​Framework Integration

​Ruby SDK

​Prerequisites

​Installation

​Basic Configuration

​PHP SDK

​Prerequisites

​Installation

​Basic Configuration

​Environment Configuration

​Development Environment

​Production Environment

​Docker Configuration

​Troubleshooting

​Common Issues

​Debug Mode

​Health Check Script

​Next Steps

​Support

SDK Installation & Setup Guide

Supported SDKs

Node.js SDK

Prerequisites

Installation

Quick Setup

Basic Configuration

Framework Integration

Python SDK

Prerequisites

Installation

Basic Configuration

Framework Integration

Ruby SDK

Prerequisites

Installation

Basic Configuration

PHP SDK

Prerequisites

Installation

Basic Configuration

Environment Configuration

Development Environment

Production Environment

Docker Configuration

Troubleshooting

Common Issues

Debug Mode

Health Check Script

Next Steps

Support