Agent Offer Network TypeScript SDK

TypeScript SDK for querying and formatting AON offers.

Taxonomy v1

Active offer payloads use AON Taxonomy v1 category ids:

import { initialize, type Offer, type QueryOffersParams } from "@agentoffernetwork/sdk";

const params: QueryOffersParams = {
  intent: { content: [{ type: "input_text", text: "compare credit card offers" }] },
  context: {
    platform: { name: "shopping-bot", channel: "api" },
    session: { recentTopics: ["credit cards"] },
  },
  constraints: {
    categoryIds: ["finance.credit_lending"],
  },
};

const client = await initialize({ placementId: "plc_home_feed_1", mode: "mock" });
const result = await client.queryOffers(params);

console.log(result.requestId);
const offer: Offer = result.offers[0];
console.log(offer.offerInfo.category.id);

Wire requests serialize constraints.categoryIds to constraints.category_ids. Offer responses expose offer_info.category as { "id": "<taxonomy_v1_category_id>" }. Parent ids match the selected taxonomy node and descendants.

Protocol v1.0

queryOffers explicitly sends AON-Protocol-Version: 1.0 and serializes the canonical stable v1.0 Query shape, which is wire-equivalent to final v0.3. New integrations should send current-turn intent, bounded session context, optional structured signals, and explicit constraints. The legacy context.userProfile and pagination SDK inputs remain accepted temporarily for source compatibility, but they are not emitted on the v1.0 wire. Use intent.signals rather than forwarding a long-term user profile.

Examples

{
  "offer_info": {
    "category": {
      "id": "arts_entertainment.igaming"
    }
  },
  "targeting": [
    {
      "geo": { "include": ["GB"] },
      "language": "en"
    }
  ]
}

The SDK does not expose a public policy object; geo, language, device, and OS restrictions remain in targeting.

Placements

Every client is created with the placementId (plc_…) of a placement you created in the AON Developer Portal — that is the only identity a Query integration needs. The SDK sends it as the X-AON-Placement-Id header, and the server routes the query by that placement's (type, data_source), AdMob-style: you don't pick the data source, the placement record does.

import { initialize, type QueryOffersParams } from "@agentoffernetwork/sdk";

const client = await initialize({ placementId: "plc_home_feed_1", mode: "live" });

const params: QueryOffersParams = {
  intent: { content: [{ type: "input_text", text: "noise cancelling headphones" }] },
  context: { platform: { name: "shopping-bot", channel: "api" } },
};
const result = await client.queryOffers(params);

The client sends your placement id in the X-AON-Placement-Id header on every query. Invalid placements (empty/unknown/inactive) return INVALID_PLACEMENT; an offerwall catalog placement with an empty pool returns CATALOG_NO_AVAILABLE_OFFERS.

Migration

Before, legacy payloads used a draft category object:

{
  "offer_info": {
    "category": {
      "type": "legacy source token",
      "attributes": {
        "legacy detail": "legacy source value"
      }
    }
  }
}

After, new integrations use:

{
  "offer_info": {
    "category": {
      "id": "computers_electronics.computers.software"
    }
  }
}

migrateLegacyCategoryToCategoryId() is deprecated and exists only for stored payload migration. New integrations should pass taxonomy v1 ids directly.