@agentoffernetwork/sdk

TypeScript SDK for Agent Offer Network — connect your LLM agent to a marketplace of product and service offers.

Features

• Intent-driven search — describe what the user wants in natural language, get matched offers
• Multimodal intent — text + image support (OpenAI-compatible content parts format)
• Click & conversion tracking — full attribution pipeline for monetization
• Recommendation formatting — ready-to-display output with disclosure labels
• Zero dependencies — uses native fetch (Node 18+)
• Dual mode — mock for development, live for production

Install

npm install @agentoffernetwork/sdk

Quick Start

import { initialize } from '@agentoffernetwork/sdk';

// Initialize (mock mode for development)
const client = await initialize({
  apiKey: 'your-api-key',
  mode: 'mock',
});

// Search offers by intent
const result = await client.queryOffers({
  intent: {
    content: [{ type: 'text', text: 'noise-cancelling headphones under $300' }],
  },
  limit: 5,
});

// Display results
for (const offer of result.offers) {
  console.log(client.formatRecommendation(offer, { style: 'markdown' }));
}

API

initialize(config): Promise<AgentOfferClient>

Create an SDK client instance.

const client = await initialize({
  apiKey: 'your-api-key',       // Required
  mode: 'mock',                  // 'mock' | 'live'
  baseUrl: 'https://api.agentoffernetwork.com', // Optional, default shown
  timeout: 5000,                 // Optional, ms
});

client.queryOffers(params): Promise<QueryOffersResponse>

Search offers by user intent.

const result = await client.queryOffers({
  intent: {
    content: [
      { type: 'text', text: 'project management tool for small teams' },
    ],
  },
  context: {                     // Optional — improves matching
    platform: 'chatgpt',
    locale: 'en',
    region: 'US',
    currency: 'USD',
  },
  limit: 10,                    // Default 10, max 50
  offset: 0,                    // Pagination
});

// result.offers    — Offer[]
// result.total     — number
// result.hasMore   — boolean

client.reportClick(event): Promise<ClickResult>

Track when a user clicks an offer.

const click = await client.reportClick({
  offerId: offer.id,
  trackingUrl: offer.trackingUrl,
  timestamp: new Date().toISOString(),
  context: null,
});

// click.clickId   — use for conversion attribution
// click.timestamp

client.reportConversion(event): Promise<void>

Track when a user completes a purchase.

await client.reportConversion({
  offerId: offer.id,
  clickId: click.clickId,
  revenue: { amount: 29.99, currency: 'USD', display: '$29.99' },
  timestamp: new Date().toISOString(),
  metadata: null,
});

client.formatRecommendation(offer, options?): string

Format an offer as display text.

// Styles: 'brief' | 'detailed' | 'markdown'
const text = client.formatRecommendation(offer, {
  style: 'markdown',
  includeDisclosure: true,       // Default true
  disclosureText: 'Sponsored',   // Default 'Sponsored'
  includePrice: true,            // Default true
});

Context

The optional QueryContext helps the backend improve matching. Fill in what's available:

| Field | Type | Example | Purpose | |-------|------|---------|---------| | platform | string | 'chatgpt', 'claude-mcp' | Platform identification | | locale | string | 'en', 'zh-CN' | Language matching | | region | string | 'US', 'JP' | Geo-filtering | | currency | string | 'USD', 'CNY' | Price display | | conversationId | string | UUID | Dedup within session | | userId | string | — | Personalization |

Error Handling

import {
  AonAuthError,
  AonRateLimitError,
  AonNetworkError,
  AonValidationError,
  AonApiError,
} from '@agentoffernetwork/sdk';

try {
  const result = await client.queryOffers({ /* ... */ });
} catch (err) {
  if (err instanceof AonAuthError) {
    // Invalid API key (401)
  } else if (err instanceof AonRateLimitError) {
    // Too many requests (429)
  } else if (err instanceof AonNetworkError) {
    // Network/timeout error
  } else if (err instanceof AonValidationError) {
    // Invalid parameters
  } else if (err instanceof AonApiError) {
    // Business logic error (err.code, err.message)
  }
}

Modes

| Mode | Use case | Backend | |------|----------|---------| | mock | Development & testing | Built-in mock data (21 offers, 3 categories) | | live | Production | https://api.agentoffernetwork.com |

Platform Integrations

This SDK is the foundation for agent platform integrations:

| Platform | Integration | Package | |----------|-------------|---------| | Claude (MCP) | MCP tool server | @aon/demo-skill | | ChatGPT | OpenAPI Action | Direct API (see sdk/openapi.json) | | Coze / Dify | HTTP Plugin | Direct API (see sdk/openapi.json) | | Custom Agent | Code integration | This SDK |

License

MIT