@katanga/sdk-supplier

Supplier agent SDK for the Katanga agent-to-agent marketplace protocol on Flare Network.

Install

npm install @katanga/sdk-supplier

Usage

import { SupplierAgent, ShopifyAdapter } from "@katanga/sdk-supplier";

const agent = new SupplierAgent({
  publicClient,
  walletClient,
  marketAddress: "0x...",
  escrowAddress: "0x...",
  metadataURI: "ipfs://...",
  source: new ShopifyAdapter({
    shopDomain: "mystore.myshopify.com",
    accessToken: "shpat_...",
  }),
  pricing: { marginPercent: 30, minimumMarginUSD: 1.0 },
  fulfillment: { autoAccept: true, maxConcurrentOrders: 50 },
});

await agent.start();
// Agent now: syncs catalog/stock/prices, watches for orders,
// auto-accepts, places source orders, tracks fulfillment, marks shipped

Adapters (7 total)

| Adapter | Status | Auth | Capabilities | |---------|--------|------|-------------| | ShopifyAdapter | Full | Access token | Stock, pricing, fulfillment, webhooks, HMAC | | CJDropshippingAdapter | Full | API key / email+password | Catalog, orders (no quantitative stock) | | NetSuiteAdapter | Stub | OAuth 1.0 TBA | SuiteQL queries, REST API, multi-warehouse | | SAPAdapter | Stub | OAuth 2.0 / Basic | OData v4, S/4HANA Cloud endpoints | | QuickBooksAdapter | Stub | OAuth 2.0 | QBO REST v3, auto-refresh tokens | | ZendropAdapter | Stub | API key | Awaiting API access | | SpocketAdapter | Stub | API key | Awaiting API access |

All adapters implement SupplySourceAdapter with: connect, healthCheck, fetchProducts, getStockLevels, getCurrentPrices, placeOrder, getFulfillmentStatus, cancelOrder.

Runner

Deploy as a long-running service:

# Development
KATANGA_CHAIN_ID=114 \
KATANGA_PRIVATE_KEY=0x... \
KATANGA_ADAPTER_TYPE=shopify \
KATANGA_SHOPIFY_DOMAIN=mystore.myshopify.com \
KATANGA_SOURCE_SHOPIFY_TYPE=api_key \
KATANGA_SOURCE_SHOPIFY_API_KEY=shpat_... \
KATANGA_METADATA_URI=ipfs://Qm... \
pnpm runner

# Production
node dist/runner.js

# Help
pnpm runner -- --help

Supported adapter types: cj, shopify, netsuite, sap, quickbooks, zendrop, spocket

Agent Features

• Catalog sync — polls source for product changes, auto-creates/deactivates listings
• Stock sync — deactivates listings at low stock, reactivates on restock
• Price sync — updates on-chain prices when source cost changes (with margin rules)
• Fulfillment pipeline — places source orders after on-chain accept, polls fulfillment status, auto-marks shipped with tracking
• Circuit breaker — exponential backoff on source failures, deactivates all listings when circuit opens
• WebhookServer — optional HTTP server for push-capable sources (Shopify, etc.)

License

MIT