Developer guide · miner SDK

Orenya Commerce Agent

Open TypeScript SDK to run the flagship Amazon miner or deploy your own agent on the Orenya network. LLM intent parsing, catalog search, deterministic scoring, and transparent SSE traces — the same pipeline validators will attest.

Introduction

Orenya is an open agent stack for AI commerce miners — not a closed platform catalog. Operators connect a product search API (Amazon, Shopify, custom), run inference through the SDK, and stream step-by-step session traces for network rewards. You can also embed the widget on any storefront.

Division of responsibility

Your marketplace provides	Commerce Agent handles
`searchProducts(query)` — product retrieval	User intent analysis (LLM)
Catalog data (IDs, titles, prices, images)	Product scoring vs. shopper intent
Checkout, inventory, fulfillment	Personalization and constraint matching
Your brand, theme, and UX	Recommendation generation (best matches + more picks)

Reduced integration complexity

You do not need to build LLM pipelines, scoring heuristics, or recommendation logic. Implement two catalog endpoints (or reuse existing ones), configure the SDK, and embed the widget.

Packages

Package	Role
`@commerce-agent/core`	Intent parsing, scoring, agent orchestration
`@commerce-agent/server`	REST + SSE API for your backend
`@commerce-agent/widget`	Embeddable, themeable chat UI for any storefront

Integration model

The agent calls your catalog through a thin HTTP contract. If you already expose product search internally, map it to these routes:

Endpoint	Purpose
`GET /search/find_product`	Search — equivalent to `searchProducts(query)`
`GET /search/view_product_information`	Product details for scoring (attributes, descriptions)

Catalog contracttypescript

// Your marketplace already has product search.
// Expose it behind two HTTP endpoints the agent calls:

// GET /search/find_product?q=wireless+earbuds&page=1&price=0-50
// → Product[]

// GET /search/view_product_information?product_ids=SKU1,SKU2
// → { product_id, title, description, attributes }[]

// Conceptually:
async function searchProducts(query: string): Promise<Product[]> {
  return catalogClient.findProduct({ q: query, page: 1 });
}

Product shapetypescript

interface Product {
  product_id: string;   // required — your SKU / ASIN / listing ID
  title?: string;
  price?: number;       // USD or your marketplace currency
  image?: string;
  shop_id?: string;
  brand?: string;
  service?: string[];   // e.g. prime, freeShipping
}

Getting started

Install the SDK, connect your catalog API, and embed the widget on your marketplace. The live demo on this site uses Rainforest API as a sample catalog for testing only — replace it with your own search backend in production.

Installation

Requires Node.js 18+ and npm.

SDKbash

npm install commerce-agent-js

Quick start

Connect your marketplace catalog and LLM key:

Express servertypescript

import { createCommerceAgentRouter } from "@commerce-agent/server";

createCommerceAgentRouter({
  agentConfig: {
    useLocalAgent: true,
    productApi: {
      baseUrl: process.env.MARKETPLACE_CATALOG_URL, // your search API
      apiKey: process.env.MARKETPLACE_API_KEY,       // optional
    },
    llm: {
      baseUrl: process.env.LLM_BASE_URL,
      apiKey: process.env.LLM_API_KEY,
      model: "gpt-4o-mini",
    },
  },
  corsOrigins: ["https://your-marketplace.com"],
}).mount(app);

Embed widgethtml

<!-- Orenya-hosted widget (or self-host commerce-agent-widget.js) -->
<script src="https://orenya.xyz/widget/commerce-agent-widget.js"></script>
<script>
  CommerceAgentWidget.init({
    apiUrl: "https://orenya.xyz/api/agent",
    delegateProductApi: false,
    theme: {
      mode: "dark", // or "light" | "auto" (follows data-theme / system)
      primaryColor: "#ff9138",
      position: "bottom-right",
    },
    title: "Shopping Assistant",
    greeting: "What are you looking for? I'll find the best matches.",
    placeholder: "e.g. wireless earbuds under $50",
    onProductClick: (product) => {
      window.location.href = "/product/" + product.product_id;
    },
  });
</script>

Packages

Core SDK

Use runCommerceAgent programmatically with your CatalogApiClient or a custom ProductApiPort.

Custom marketplacetypescript

import { CommerceAgent, CatalogApiClient, runCommerceAgent } from "@commerce-agent/core";

// Plug in your marketplace catalog
const catalog = new CatalogApiClient({
  baseUrl: "https://api.your-marketplace.com",
  apiKey: process.env.MARKETPLACE_API_KEY,
});

const result = await runCommerceAgent(
  "Find waterproof running shoes under $100, Nike preferred",
  catalog,
  {
    llm: {
      baseUrl: process.env.LLM_BASE_URL!,
      apiKey: process.env.LLM_API_KEY!,
    },
  },
);

// Agent output — you render these in your UI
console.log(result.bestMatches);      // top picks after scoring
console.log(result.recommendations);  // additional matches

Server

Mount createCommerceAgentRouter on Express (or use the built-in Next.js routes in this repo's website/ demo). The server holds your LLM key — never expose it in the browser.

Router setuptypescript

import { createCommerceAgentRouter } from "@commerce-agent/server";

createCommerceAgentRouter({
  agentConfig: {
    useLocalAgent: true,
    productApi: {
      baseUrl: process.env.MARKETPLACE_CATALOG_URL, // your search API
      apiKey: process.env.MARKETPLACE_API_KEY,       // optional
    },
    llm: {
      baseUrl: process.env.LLM_BASE_URL,
      apiKey: process.env.LLM_API_KEY,
      model: "gpt-4o-mini",
    },
  },
  corsOrigins: ["https://your-marketplace.com"],
}).mount(app);

Widget

The widget is fully customizable: theme colors, position, greeting, placeholder, title, and onProductClick. Each marketplace ships its own branded assistant while sharing the same agent core.

Production embedhtml

<!-- Orenya-hosted widget (or self-host commerce-agent-widget.js) -->
<script src="https://orenya.xyz/widget/commerce-agent-widget.js"></script>
<script>
  CommerceAgentWidget.init({
    apiUrl: "https://orenya.xyz/api/agent",
    delegateProductApi: false,
    theme: {
      mode: "dark", // or "light" | "auto" (follows data-theme / system)
      primaryColor: "#ff9138",
      position: "bottom-right",
    },
    title: "Shopping Assistant",
    greeting: "What are you looking for? I'll find the best matches.",
    placeholder: "e.g. wireless earbuds under $50",
    onProductClick: (product) => {
      window.location.href = "/product/" + product.product_id;
    },
  });
</script>

Browser-delegated search (optional)

If you prefer the browser to call your catalog API directly (agent logic still runs server-side), enable delegation:

javascript

// Alternative: browser calls YOUR search API directly
CommerceAgentWidget.init({
  apiUrl: "https://api.your-marketplace.com/api/agent",
  delegateProductApi: true,
  productApi: {
    baseUrl: "https://api.your-marketplace.com",
    apiKey: "optional-bearer-token",
  },
});

Agent API reference

Routes mounted under /api/agent on your backend:

Method	Path	Description
POST	`/sessions`	Create chat session
POST	`/sessions/:id/messages`	Send message → `AgentResult`
GET	`/sessions/:id/stream?message=`	SSE stream (intent steps + recommendations)
GET	`/health`	`{ ok, hasLlm, hasServerProductApi }`

AgentResult

typescript

interface AgentResult {
  status: "success" | "failure";
  bestMatches: Product[];       // scored top picks
  recommendations: Product[];   // more from search pool
  productIds: string[];
  steps: DialogueStep[];        // intent + scoring reasoning
}

Environment variables

Production marketplacebash

# Your production deployment
MARKETPLACE_CATALOG_URL=https://api.your-marketplace.com
MARKETPLACE_API_KEY=optional
LLM_API_KEY=sk-...
LLM_BASE_URL=https://api.openai.com/v1

Variable	Required	Description
`MARKETPLACE_CATALOG_URL` / `PRODUCT_API_URL`	Yes	Base URL of your `searchProducts` API
`MARKETPLACE_API_KEY` / `PRODUCT_API_KEY`	No	Bearer token for your catalog API
`LLM_API_KEY`	Yes	OpenAI-compatible key for intent extraction
`LLM_BASE_URL`	No	Default `https://api.openai.com/v1`
`RAINFOREST_API_KEY`	Demo only	Sample catalog on orenya.xyz — not for production

Architecture

Request flowtext

Your marketplace storefront
    │  embeddable widget (customized theme + handlers)
    ▼
Commerce Agent API (/api/agent)
    │
    ├─ User intent analysis      (LLM extracts keywords, brand, features, budget)
    ├─ searchProducts(query)     → YOUR catalog API
    ├─ Product scoring           (relevance vs. user intent)
    ├─ Personalization           (constraints, preferences, context)
    └─ Recommendation generation (bestMatches + recommendations)

Your marketplace provides search. Orenya provides the intelligence layer.

Repository layouttext

commerce-agent-js/
├── packages/core/        intent parsing, scoring, agent logic
├── packages/server/      REST + SSE API for your backend
├── packages/widget/      embeddable, themeable chat UI
└── examples/express-server/