SDK Reference

Authoritative API signatures, runtime behavior, and integration notes for the official AON SDK.

Use the TypeScript SDK for your application. Live use needs the same placement id of a placement in a serviceable Application as the REST route.

Authoritative source

Use the pages in this section as the source of truth for exported methods, option names, and response shapes. The Guides section is tutorial-first; this section is signature-first.

Identity and access

SDK reference material does not establish account eligibility or live runtime availability. For identity mechanics, use Authentication.

Available SDKs

SDK	Language	Package	Status
TypeScript	TypeScript / JavaScript	`@agentoffernetwork/sdk`	v1.1.0

Choose Your Reference

Page	Use when	Covers
TypeScript SDK	You are integrating from Node.js, edge runtimes, or browser-adjacent JavaScript	`initialize`, `queryOffers`, `reportClick`, `formatRecommendation`, `detectContext`, mock testing

Shared Workflow

The SDK can validate local construction in mock mode, but that is not the default live workflow. Initialize it in live mode with your placement id, and complete its queryOffers check before adding tracking or conversion behavior.

Method Map

Capability	TypeScript	Notes
Initialize client	`await initialize(config)`	Validates placement id, mode, and timeout before constructing a live or mock client
Search offers	`client.queryOffers(params)`	Sends `POST /v1/offers/query` in live mode
Track click	`client.reportClick(event)`	Calls the returned tracking URL directly
Format offer	`client.formatRecommendation(...)`	Also exported as a standalone formatter
Explicit platform adapter	`createContextForPlatform(target, options?)`	Use this when the host platform is already known and you want stable platform attribution
Detect context	`detectContext(overrides?)`	Builds `QueryContext` defaults for platform, language, and session
Inspect mock events	`mock.getRecordedEvents()`	Available only on mock clients

Common Runtime Behavior

mode: "mock" uses in-memory data and never calls the network.
mode: "live" / mode="live" identifies requests with your placement id (X-AON-Placement-Id) and talks to https://api.aon.pro by default.
Query intent content must contain at least one input_text or input_image part.
reportClick returns a trackingId that you pass into conversion tracking.
formatRecommendation supports brief, detailed, and markdown output.
Use the explicit platform adapter helpers for mcp-skill, chatgpt, coze, and dify; keep detectContext for legacy runtime auto-detection.

Source-of-truth note

Use the Guides section when you want tutorial-style onboarding.
Use this SDK section when you want signature-first reference pages.
For current package versions and runtime requirements, this docs site is pinned to the baselines confirmed in the repository: TypeScript v1.1.0 and Node 20+.

SDK live completion path

Use the TypeScript SDK path. A local mock result is not live completion; a live query with the placement id of a serviceable Application must produce the canonical v1.0 query success.

To get the placement id, see Get your Placement ID or Authentication.

SDK Setup for the full end-to-end tutorial
TypeScript SDK Guide for tutorial-style examples
Best Practices for retry, caching, and production patterns

Use the TypeScript SDK

SDK Setup