| name | commerce-embedded-sdk |
| description | Integrate the StateSet iCommerce embedded SDK in apps. Use when creating a Commerce client, configuring `@stateset/embedded`, or wiring embedded SDK calls. |
Commerce Embedded SDK
Use the embedded engine from application code via language bindings.
How It Works
- Install the binding for the target language.
- Initialize
Commerce with a SQLite database path.
- Call module APIs (customers, products, inventory, orders, etc).
- Run the matching example to validate behavior.
- Enable sync to push local events to the sequencer for multi-node consistency.
Status Flows
- SDK Init: not_installed -> installed -> initialized -> ready
- Sync Session: idle -> pushing -> pulling -> synced | conflict
Usage
- CLI:
stateset --db ./store.db "list products" (uses embedded SDK internally)
- Node.js:
npm install @stateset/embedded
- Python:
pip install stateset-embedded
- Rust:
cargo add stateset-embedded
- MCP tools: all commerce tools use the embedded SDK as the data layer.
- See language examples under
/home/dom/stateset-icommerce/examples/
Permissions
- Read:
list_products, list_customers, list_orders, version() — no --apply needed.
- Write:
create_order, update_customer, sync push — requires --apply.
Examples
npm install @stateset/embedded && node -e "const {Commerce}=require('@stateset/embedded'); const c=new Commerce('/tmp/commerce.db'); console.log(c.version())"
pip install stateset-embedded && python -c "from stateset_embedded import Commerce; c=Commerce('/tmp/commerce.db'); print(c.version())"
cargo run --example basic_usage -- --db /tmp/commerce.db
stateset embedded sync --db /tmp/commerce.db --sequencer https://seq.stateset.io
Output
{"status":"ok","order_number":"ORD-12345","customer_id":"cust_123","db_path":"/tmp/commerce.db","sdk_version":"0.9.4","email":"cust@example.com","sku":"WIDGET-001","amount":150.00}
Present Results to User
- Binding used and database path.
- Which example or module calls were validated.
- Any build or runtime constraints.
- SDK version and sync readiness state.
Troubleshooting
- Binding build errors: confirm Rust toolchain and target platform.
- Shared library issues: check
LD_LIBRARY_PATH or platform linking.
- Missing symbols: rebuild the native bindings for your runtime.
db_path not writable: verify directory permissions and disk space with df -h.
Error Codes
SDK_BINDING_BUILD_FAILED: Native binding compilation failed; check Rust toolchain and target platform.SDK_DB_NOT_WRITABLE: The database path is not writable; verify directory permissions.SDK_SYMBOL_MISSING: Required native symbol not found; rebuild bindings for the current runtime.
Related Skills
- commerce-sync -- push embedded events to the sequencer after local writes.
- commerce-orders -- validate order workflows created through the SDK.
- commerce-customers -- manage customer records the SDK interacts with.
- commerce-autonomous-engine -- run scheduled jobs against the embedded database.
References
- references/bindings.md
- /home/dom/stateset-icommerce/examples/README.md
- /home/dom/stateset-icommerce/examples/basic_usage.rs
- /home/dom/stateset-icommerce/examples/node/basic_usage.js
- /home/dom/stateset-icommerce/examples/python/basic_usage.py
