StateSet iCommerce Engine

The SQLite of Commerce - An embedded, zero-dependency commerce engine for autonomous AI agents.

AI agents that reason, decide, and execute—replacing tickets, scripts, and manual operations across your entire commerce stack.

34 new MCP tools expanding full commerce coverage:

Install:

pip install stateset-embedded==0.1.7    # Python
gem install stateset_embedded -v 0.1.7  # Ruby
npm install @stateset/embedded@0.1.7    # Node.js
cargo add stateset-embedded             # Rust

Commerce is undergoing a fundamental shift. Where eCommerce was built for humans clicking buttons in dashboards, iCommerce (Intelligent Commerce) is built for AI agents making decisions.

StateSet enables this shift by providing a portable, embeddable commerce engine that agents can carry with them.

stateset-icommerce/
├── crates/
│   ├── stateset-core/       # Pure domain models & business logic (no I/O)
│   ├── stateset-db/         # SQLite + PostgreSQL implementations
│   └── stateset-embedded/   # Unified high-level API
├── bindings/
│   ├── node/                # JavaScript/TypeScript (NAPI)
│   ├── python/              # Python (PyO3)
│   ├── ruby/                # Ruby (Magnus)
│   ├── php/                 # PHP (ext-php-rs)
│   ├── java/                # Java (JNI)
│   └── wasm/                # WebAssembly (browser + Node)
└── cli/
    ├── bin/                 # 14 CLI programs
    ├── src/                 # MCP server (87 tools)
    └── .claude/             # 8 AI agents, 7 skills

┌─────────────────────────────────────────────────────────────────┐
│                       AI Agent Layer                            │
│              (Claude, ChatGPT, Gemini, Custom)                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                   Agentic Commerce Protocol (ACP)
                              │
┌─────────────────────────────────────────────────────────────────┐
│                     StateSet iCommerce                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │   Models    │  │   Storage   │  │  Execution  │             │
│  │ 254 types   │  │SQLite/Postgres│ │Deterministic│             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │  87 MCP     │  │  8 Agents   │  │  7 Skills   │             │
│  │   Tools     │  │ Specialized │  │  Knowledge  │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
└─────────────────────────────────────────────────────────────────┘

use stateset_embedded::Commerce;
use rust_decimal_macros::dec;

// Initialize with a local database file
let commerce = Commerce::new("./store.db")?;

// Create a customer
let customer = commerce.customers().create(CreateCustomer {
    email: "alice@example.com".into(),
    first_name: "Alice".into(),
    last_name: "Smith".into(),
    ..Default::default()
})?;

// Create inventory
commerce.inventory().create_item(CreateInventoryItem {
    sku: "SKU-001".into(),
    name: "Widget".into(),
    initial_quantity: Some(dec!(100)),
    ..Default::default()
})?;

// Create an order
let order = commerce.orders().create(CreateOrder {
    customer_id: customer.id,
    items: vec![CreateOrderItem {
        sku: "SKU-001".into(),
        name: "Widget".into(),
        quantity: 2,
        unit_price: dec!(29.99),
        ..Default::default()
    }],
    ..Default::default()
})?;

// Ship the order
commerce.orders().ship(order.id, Some("FEDEX123456".into()))?;

const { Commerce } = require('@stateset/embedded');

const commerce = new Commerce('./store.db');

// Create a cart and checkout
const cart = await commerce.carts.create({
  customerEmail: 'alice@example.com',
  customerName: 'Alice Smith'
});

await commerce.carts.addItem(cart.id, {
  sku: 'SKU-001',
  name: 'Widget',
  quantity: 2,
  unitPrice: 29.99
});

const result = await commerce.carts.complete(cart.id);
console.log(`Order created: ${result.orderNumber}`);

// Convert currency
const conversion = await commerce.currency.convert({
  from: 'USD',
  to: 'EUR',
  amount: 100
});
console.log(`$100 USD = €${conversion.convertedAmount} EUR`);

from stateset import Commerce

commerce = Commerce('./store.db')

# Get analytics
summary = commerce.analytics.sales_summary(period='last30days')
print(f"Revenue: ${summary.total_revenue}")
print(f"Orders: {summary.order_count}")

# Forecast demand
forecasts = commerce.analytics.demand_forecast(days_ahead=30)
for f in forecasts:
    if f.days_until_stockout and f.days_until_stockout < 14:
        print(f"WARNING: {f.sku} will stock out in {f.days_until_stockout} days")

require 'stateset_embedded'

commerce = StateSet::Commerce.new('./store.db')

# Create a customer
customer = commerce.customers.create(
  email: 'alice@example.com',
  first_name: 'Alice',
  last_name: 'Smith'
)

# Create an order
order = commerce.orders.create(
  customer_id: customer.id,
  items: [
    { sku: 'SKU-001', name: 'Widget', quantity: 2, unit_price: 29.99 }
  ]
)

# Manage subscriptions
plan = commerce.subscriptions.create_plan(
  name: 'Pro Monthly',
  price: 29.99,
  interval: 'month'
)

subscription = commerce.subscriptions.subscribe(
  plan_id: plan.id,
  customer_id: customer.id
)

<?php
use StateSet\Commerce;

$commerce = new Commerce('./store.db');

// Create a customer
$customer = $commerce->customers()->create(
    email: 'alice@example.com',
    firstName: 'Alice',
    lastName: 'Smith'
);

// Create an order
$order = $commerce->orders()->create(
    customerId: $customer->getId(),
    items: [
        ['sku' => 'SKU-001', 'name' => 'Widget', 'quantity' => 2, 'unit_price' => 29.99]
    ]
);

// Calculate tax
$tax = $commerce->tax()->calculate(
    amount: 100.00,
    jurisdictionId: $jurisdiction->getId()
);

// Apply promotions
$promo = $commerce->promotions()->create(
    code: 'SUMMER20',
    name: 'Summer Sale',
    discountType: 'percentage',
    discountValue: 20.0
);

import com.stateset.embedded.*;

try (Commerce commerce = new Commerce("./store.db")) {
    // Create a customer
    Customer customer = commerce.customers().create(
        "alice@example.com",
        "Alice",
        "Smith"
    );

    // Create an order
    Order order = commerce.orders().create(
        customer.getId(),
        "USD"
    );

    // Process payments
    commerce.payments().recordPayment(
        order.getId(),
        order.getTotalAmount(),
        "card",
        "txn_123456"
    );

    // Get analytics
    SalesSummary summary = commerce.analytics().salesSummary(30);
    System.out.println("Revenue: $" + summary.getTotalRevenue());
}

# Natural language interface
stateset "show me pending orders"
stateset "what's my revenue this month?"
stateset "convert $100 USD to EUR"

# Execute operations (requires --apply)
stateset --apply "create a cart for alice@example.com"
stateset --apply "ship order #12345 with tracking FEDEX123"
stateset --apply "approve return RET-001"

# Tax calculation
stateset "calculate tax for an order shipping to California"
stateset "what's the VAT rate for Germany?"

# Promotions
stateset --apply "create a 20% off promotion called Summer Sale"
stateset "is coupon SAVE20 valid?"
stateset --apply "apply promotions to cart CART-123"

# Subscriptions
stateset "show me all subscription plans"
stateset --apply "create a monthly plan called Pro at $29.99"
stateset --apply "subscribe customer alice@example.com to the Pro plan"

# Payments & Refunds
stateset "list payments for order #12345"
stateset --apply "create payment for order #12345 amount $99.99 via card"
stateset --apply "refund payment PAY-001 amount $25.00"

# Shipments
stateset --apply "create shipment for order #12345 via FedEx tracking FEDEX123"
stateset --apply "mark shipment SHIP-001 as delivered"

# Supply Chain
stateset "list purchase orders"
stateset --apply "create purchase order for supplier SUP-001"
stateset --apply "approve purchase order PO-001"

# Invoices (B2B)
stateset "show overdue invoices"
stateset --apply "create invoice for customer CUST-001"
stateset --apply "record payment on invoice INV-001"

# Warranties
stateset "list warranties for customer CUST-001"
stateset --apply "create warranty for product SKU-001"
stateset --apply "file warranty claim for warranty WRN-001"

# Manufacturing
stateset "list bills of materials"
stateset --apply "create BOM for product WIDGET-ASSEMBLED"
stateset --apply "add component SKU-PART-A quantity 2 to BOM-001"
stateset --apply "create work order from BOM-001 quantity 50"
stateset --apply "complete work order WO-001 with 48 units produced"

Core: customers, customer_addresses, products, product_variants, orders, order_items

Inventory: inventory_items, inventory_locations, inventory_balances, inventory_transactions, inventory_reservations

Financial: payments, refunds, payment_methods, invoices, invoice_items, purchase_orders, purchase_order_items

Fulfillment: shipments, shipment_items, shipment_events, returns, return_items

Manufacturing: manufacturing_boms, manufacturing_bom_components, manufacturing_work_orders, manufacturing_work_order_tasks, manufacturing_work_order_materials

Tax: tax_jurisdictions, tax_rates, tax_exemptions, tax_settings

Promotions: promotions, promotion_rules, promotion_actions, coupons, coupon_usages, promotion_applications

Subscriptions: subscription_plans, subscriptions, billing_cycles, subscription_events

Other: warranties, warranty_claims, carts, cart_items, exchange_rates, store_currency_settings, product_currency_prices, exchange_rate_history, events

The MCP server exposes 87 tools for AI agent integration:

Eight specialized agents for different commerce domains:

• Full order lifecycle (create → confirm → ship → deliver)
• Multi-location inventory with reservations
• Customer profiles with addresses
• Product catalog with variants and attributes

• Multi-currency support (35+ currencies including BTC, ETH, USDC)
• Payment processing with multiple methods
• Refund management
• Invoice generation
• Purchase orders with suppliers

• Multi-jurisdiction tax calculation (US, EU, Canada)
• State/province tax rates with automatic lookup
• Tax exemptions and certificates
• VAT support for EU countries
• GST/HST/PST for Canadian provinces

• Percentage and fixed-amount discounts
• Coupon codes with usage limits
• Buy-X-Get-Y promotions
• Free shipping promotions
• Time-limited campaigns

• Flexible subscription plans (daily, weekly, monthly, annual)
• Free trial periods
• Billing cycle management
• Pause/resume/cancel lifecycle
• Skip billing cycles

• Manufacturing BOMs (Bill of Materials)
• Work orders with task tracking
• Shipment tracking with carrier integration
• Returns/RMA processing

• Sales summaries and revenue trends
• Demand forecasting per SKU
• Revenue projections with confidence intervals
• Inventory health monitoring
• Customer metrics and LTV

• Deterministic operations for agent reliability
• MCP protocol integration (87 tools)
• Safety architecture (--apply flag for writes)
• Event-driven for full auditability
• Portable state in single database file

[dependencies]
stateset-embedded = "0.1"
rust_decimal = "1.36"
rust_decimal_macros = "1.36"

npm install @stateset/embedded

pip install stateset-embedded

gem install stateset_embedded

Or add to your Gemfile:

gem 'stateset_embedded'

composer require stateset/embedded

# Install the native extension for best performance
composer install-extension

Then add to your php.ini:

extension=stateset_embedded

<dependency>
    <groupId>com.stateset</groupId>
    <artifactId>embedded</artifactId>
    <version>0.1.7</version>
</dependency>

implementation 'com.stateset:embedded:0.1.7'

cd cli
npm install
npm link

# Verify installation
stateset --help

StateSet provides native bindings for 7 languages, all built from the same Rust core:

Laravel (PHP)

// AppServiceProvider.php
$this->app->singleton(Commerce::class, fn() =>
    new Commerce(storage_path('stateset/commerce.db'))
);

Rails (Ruby)

# config/initializers/stateset.rb
Rails.application.config.stateset = StateSet::Commerce.new(
  Rails.root.join('db', 'commerce.db').to_s
)

Spring Boot (Java)

@Configuration
public class CommerceConfig {
    @Bean(destroyMethod = "close")
    public Commerce commerce() {
        return new Commerce("commerce.db");
    }
}

SQLite (Default):

let commerce = Commerce::new("./store.db")?;
// Or in-memory for testing
let commerce = Commerce::new(":memory:")?;

PostgreSQL:

let commerce = Commerce::with_postgres("postgres://user:pass@localhost/db")?;
// Or with options
let commerce = Commerce::builder()
    .postgres("postgres://localhost/stateset")
    .max_connections(20)
    .build()?;

export ANTHROPIC_API_KEY=sk-ant-...  # Required for AI mode
stateset --db ./store.db "list customers"

# Run Rust examples
cargo run --example basic_usage
cargo run --example manufacturing

# CLI examples
stateset "how many orders do we have?"
stateset "what's the exchange rate from USD to EUR?"
stateset --apply "add 50 units to SKU-001"

stateset-icommerce/
├── Cargo.toml                 # Workspace manifest
├── crates/
│   ├── stateset-core/         # Domain models (18 domain modules)
│   │   └── src/models/        # 254 types
│   ├── stateset-db/           # Database layer
│   │   ├── src/sqlite/        # 18 SQLite modules
│   │   ├── src/postgres/      # 8 PostgreSQL modules
│   │   └── migrations/        # 11 SQL migrations
│   └── stateset-embedded/     # High-level API
│       └── src/               # 20+ API modules
├── bindings/
│   ├── node/                  # NAPI bindings (@stateset/embedded)
│   ├── python/                # PyO3 bindings (stateset-embedded)
│   ├── ruby/                  # Magnus bindings (stateset_embedded gem)
│   ├── php/                   # ext-php-rs bindings (stateset/embedded)
│   ├── java/                  # JNI bindings (com.stateset:embedded)
│   └── wasm/                  # WebAssembly bindings (@stateset/embedded-wasm)
├── cli/
│   ├── bin/                   # 14 CLI programs
│   ├── src/mcp-server.js      # 87 MCP tools
│   └── .claude/               # 8 agents, 7 skills
└── examples/

StateSet implements the Agentic Commerce Protocol, an open standard defining how AI agents perform commerce operations:

// ACP operations are deterministic and auditable
commerce.orders.create(...)     // Create order
commerce.inventory.reserve(...) // Reserve stock
commerce.returns.approve(...)   // Approve return
commerce.currency.convert(...)  // Convert currency

All write operations require explicit opt-in:

# Preview only (safe)
stateset "create a cart for alice@example.com"

# Actually execute (requires --apply)
stateset --apply "create a cart for alice@example.com"

All operations emit events for auditability:

pub enum CommerceEvent {
    OrderCreated(Order),
    OrderStatusChanged { id, from, to },
    InventoryAdjusted { sku, delta, reason },
    PaymentProcessed(Payment),
    // ...
}

MIT OR Apache-2.0

Contributions welcome! Please read the contributing guidelines before submitting PRs.

Built with Rust for reliability, designed for AI agents.