conduit-commerce

The commerce layer for AI agents. Three function calls. Any provider. Any protocol.

Conduit is a protocol-agnostic TypeScript SDK that lets AI agents comparison-shop, route, and transact across multiple commerce providers. Think Stripe for agent-era commerce.

Quick Start

npm install conduit-commerce

import { Conduit } from 'conduit-commerce';

const conduit = new Conduit({
  providers: ['mock'],
  payment: { stripe_key: 'sk_test_...' }
});

const results = await conduit.query({
  category: 'food_delivery',
  query: 'pad thai',
  location: { lat: 36.1627, lng: -86.7816 },
  constraints: { max_price: 30, max_time_minutes: 45 }
});

const pick = await conduit.decide(results, {
  weights: { price: 0.4, speed: 0.3, reliability: 0.3 },
  dietary: ['no-peanuts'],
});

const order = await conduit.execute(pick.recommendation, {
  payment_method: 'pm_card_visa',
  delivery_address: '123 Main St, Nashville, TN'
});

console.log(order.confirmation_id);   // cnd_ord_abc123
console.log(order.tracking_url);      // provider tracking link
console.log(order.estimated_delivery); // ISO 8601 timestamp

await conduit.shutdown();

The Three Calls

conduit.query(intent)

Fans out to all configured providers simultaneously. Returns normalized results.

const results = await conduit.query({
  category: 'food_delivery',
  query: 'vegetarian options',
  location: { lat: 36.1627, lng: -86.7816 },
  constraints: {
    max_price: 25,
    max_time_minutes: 40,
    min_rating: 4.0
  }
});
// Returns: ProviderResult[] — normalized across all providers

conduit.decide(results, preferences)

Applies weighted scoring and dietary filtering. Returns a ranked recommendation with reasoning.

const pick = await conduit.decide(results, {
  weights: { price: 0.5, speed: 0.3, reliability: 0.2 },
  dietary: ['no-peanuts'],
  preferred_providers: ['local-favorite'],
  max_results: 3
});
// Returns: DecisionResult — recommendation, alternatives, reasoning

conduit.execute(selection, payment)

Places the order through the provider. Handles payment via Stripe Connect.

const order = await conduit.execute(pick.recommendation, {
  payment_method: 'pm_card_visa',
  delivery_address: '123 Main St, Nashville, TN 37201',
  tip_amount: 3.00,
  special_instructions: 'Leave at door'
});
// Returns: OrderConfirmation — confirmation_id, tracking_url, estimated_delivery

Preference Profiles

Conduit's decision engine uses weighted scoring across three dimensions:

// Price-focused
{ weights: { price: 0.7, speed: 0.2, reliability: 0.1 } }

// Speed-focused
{ weights: { price: 0.1, speed: 0.8, reliability: 0.1 } }

// Dietary-restricted
{ weights: { price: 0.4, speed: 0.3, reliability: 0.3 }, dietary: ['no-peanuts'] }

// Balanced with provider preference
{ weights: { price: 0.34, speed: 0.33, reliability: 0.33 }, preferred_providers: ['mock'] }

Provider Adapters

Built-in Adapters

| Adapter ID | Description | Status | |------------|-------------|--------| | mock | Nashville demo — 8 restaurants, full menu data | Ready | | square-online | Square Online ordering | Requires API key |

Custom Adapters

import { BaseAdapter } from 'conduit-commerce';
import type { QueryIntent, ProviderResult, PaymentInfo, OrderConfirmation } from 'conduit-commerce';

export class MyAdapter extends BaseAdapter {
  readonly id = 'my-provider';
  readonly name = 'My Provider';
  readonly supportedCategories = ['food_delivery'];

  async query(intent: QueryIntent): Promise<ProviderResult[]> {
    // Fetch from your provider, return normalized ProviderResult[]
  }

  async execute(result: ProviderResult, payment: PaymentInfo): Promise<OrderConfirmation> {
    // Place order, return OrderConfirmation
  }

  async healthCheck(): Promise<boolean> {
    return true;
  }
}

Register it:

const conduit = new Conduit({
  providers: ['my-provider'],
  provider_configs: {
    'my-provider': { adapter: new MyAdapter() }
  }
});

Configuration

interface ConduitConfig {
  providers: string[];          // adapter IDs to activate
  provider_configs?: Record<string, { adapter: ConduitAdapter }>;
  payment?: {
    stripe_key: string;         // Stripe API key (sk_test_... or sk_live_...)
  };
  ledger?: {
    path?: string;              // SQLite path (default: ./conduit-ledger.db)
    enabled?: boolean;          // default: true
  };
  timeout_ms?: number;          // per-adapter query timeout (default: 10000)
  log?: string;                 // log level: 'debug' | 'info' | 'warn' | 'error'
}

Architecture

Agent (any AI assistant)
  ↓
Conduit SDK (npm: conduit-commerce)
  ├── Query Engine    (fan-out, normalization, timeout handling)
  ├── Decision Engine (preference matching, weighted scoring)
  ├── Execution Engine (order placement, payment, confirmation)
  └── Intelligence Layer (SQLite ledger, reliability scoring)
      ↓
Provider Adapters (pluggable)
  ├── mock           (demo/testing)
  ├── square-online  (Square Online ordering)
  └── [your-adapter] (one file to add a provider)
      ↓
Payment Rail (Stripe Connect)

Roadmap

• v0.2 — DoorDash Drive and Uber Direct adapters
• v0.3 — WebMCP adapter (when standard stabilizes)
• v0.4 — Hosted intelligence API (cross-provider routing data)
• v1.0 — Enterprise tier, SLA, custom adapters

License

MIT — Sprint Labs