# SDK Reference

Source: https://docs.aon.pro/sdk

> Derived from the same AON Docs release as the source page.

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

Choose the TypeScript or Python SDK that matches your application. Live use requires the same serviceable Application and issued Live Key condition 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.

> Credentials and access
>
> SDK reference material does not establish account eligibility or live runtime availability. For credential mechanics, use [Authentication](https://docs.aon.pro/api/authentication).

## Available SDKs

| SDK | Language | Package | Status |
| --- | --- | --- | --- |
| TypeScript | TypeScript / JavaScript | `@agentoffernetwork/sdk` | v1.0.0 |
| Python | Python 3.11+ | `agentoffernetwork` | v1.0.0 |

## Choose Your Reference

| Page | Use when | Covers |
| --- | --- | --- |
| [TypeScript SDK](https://docs.aon.pro/sdk/typescript) | You are integrating from Node.js, edge runtimes, or browser-adjacent JavaScript | `initialize`, `queryOffers`, `reportClick`, `formatRecommendation`, `detectContext`, mock testing |
| [Python SDK](https://docs.aon.pro/sdk/python) | You are integrating from Python agents, async services, or notebooks | `initialize`, `query_offers`, `report_click`, `format_recommendation`, `detect_context`, mock testing |

## Shared Workflow

Both SDKs can validate local construction in `mock` mode, but that is not the default live workflow. Choose one language, initialize it in live mode with your issued Live Key, and complete its `queryOffers` / `query_offers` check before adding tracking or conversion behavior.

## Method Map

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

## Common Runtime Behavior

-   `mode: "mock"` / `mode="mock"` uses in-memory data and never calls the network.
-   `mode: "live"` / `mode="live"` authenticates with a Bearer token and talks to `https://api.aon.pro` by default.
-   Query intent content must contain at least one `input_text` or `input_image` part.
-   `reportClick` / `report_click` returns a `trackingId` / `tracking_id` that you pass into conversion tracking.
-   `formatRecommendation` / `format_recommendation` supports `brief`, `detailed`, and `markdown` output.
-   Use the explicit platform adapter helpers for `mcp-skill`, `chatgpt`, `coze`, and `dify`; keep `detectContext` / `detect_context` 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.0.0`, Python `v1.0.0`, Node 20+, Python 3.11+.

## Choose one SDK live completion path

Choose a language-specific SDK path. A local mock result is not live completion; a serviceable Application and issued Live Key must produce the canonical v1.0 query success in the language you selected.

For the shared live access condition, review [Production Access & API Keys](https://docs.aon.pro/quickstart/get-api-key) or [Authentication](https://docs.aon.pro/api/authentication).

## Related Guides

-   [SDK Setup](https://docs.aon.pro/quickstart/sdk-setup) for the full end-to-end tutorial
-   [TypeScript SDK Guide](https://docs.aon.pro/guides/sdk-typescript) for tutorial-style examples
-   [Python SDK Guide](https://docs.aon.pro/guides/sdk-python) for Python walkthroughs
-   [Best Practices](https://docs.aon.pro/guides/best-practices) for retry, caching, and production patterns

[Use the TypeScript SDK](https://docs.aon.pro/sdk/typescript)

[Use the Python SDK](https://docs.aon.pro/sdk/python)