Skip to content
Topsort Documentation
clients

Topsort Javascript library

topsort.js is the official Topsort javascript client library. This project is built with TypeScript and uses Bun for package management and testing.

Installation

Using npm:

Terminal window
npm install @topsort/sdk --save

Using yarn:

Terminal window
yarn add @topsort/sdk --save

Usage

Auctions

To create an auction, first initialize a Topsort Client, then call the createAuction function:

import { TopsortClient, Auction } from "@topsort/sdk";


const auctionDetails: Auction = {
  auctions: [
    {
      type: "listings",
      slots: 3,
      category: { id: "cat123" },
      geoTargeting: { location: "US" },
    },
    {
      type: "banners",
      slots: 1,
      device: "desktop",
      slotId: "slot123",
      category: { ids: ["cat1", "cat2"] },
      geoTargeting: { location: "UK" },
    },
  ],
};


const config = {
  // generate your api key in the auction manager - it should look some thing like this
  // note: this is an invalid key and won't work, you need to replace it with your own
  apiKey: "TSE_4S6o1g1CB5tyRENfhDMAn6viR7A5cy3j1JAR",
};


const topsortClient = new TopsortClient(config)


topsortClient.createAuction(auctionDetails)
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Parameters

config: An object containing configuration details including the API key. Please refer to Auction Manager

Config Parameters
  • apiKey: Your Topsort API Key
  • userAgent: Optional user agent to be added as part of the request. Example: Mozilla/5.0
  • timeout: Optional timeout in milliseconds. Default is 30 seconds. If timeout is reached, the call will be rejected with an AbortError.

auctionDetails: An object containing the details of the auction to be created, please refer to Topsort’s Auction API doc for body specification.

Sample response

200:

{
  "results": [
    {
      "winners": [
        {
          "rank": 1,
          "type": "product",
          "id": "p_Mfk11",
          "resolvedBidId": "WyJiX01mazExIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTMyNjYtY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=="
        }
      ],
      "error": false
    },
    {
      "winners": [],
      "error": false
    }
  ]
}

400:

{
  "status": 400,
  "statusText": "No Content",
  "body": {
    "errCode": "bad_request",
    "docUrl": "https://docs.topsort.com/reference/errors",
    "message": "The request could not be parsed.",
  },
}

Events

To report an event, first initialize a Topsort Client, then call the reportEvent function:

import { TopsortClient, Event } from "@topsort/sdk";


const event: Event = {
  impressions: [
    {
      resolvedBidId:
        "ChAGaP5D2ex-UKEEBCOHwvDjEhABkF4FDAx0S5mMD2cOG0w9GhABkEnL2CB6qKIoqeItVgA_InsKd2h0dHBzOi8vd3d3LndlYmEuYmUvZnIvcHJvbW8uaHRtbD91dG1fc291cmNlPW15c2hvcGkmdXRtX21lZGl1bT1iYW5uZXJfMTI4MHg0MDAmdXRtX2NvbnRlbnQ9ZGlzcGxheSZ1dG1fY2FtcGFpZ249c29sZGVuEAU",
      id: "1720706109.713344-53B92988-7A49-4679-B18E-465943B46149",
      occurredAt: "2024-07-11T13:55:09Z",
      opaqueUserId: "38e0a5ff-9f8a-4e80-8969-e5e3f01348e8",
      placement: {
        path: "/categories/sports",
      },
    },
  ],
};


const config = {
  // generate your api key in the auction manager - it should look some thing like this
  apiKey: "TSE_4S6o1g1CB5tyRENfhDMAn6viR7A5cy3j1JAR",
};


const topsortClient = new TopsortClient(config)


topsortClient.reportEvent(event)
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Parameters

config: An object containing configuration details including the API key. Please refer to Auction Manager

event: An object containing the details of the event to be reported, please refer to Topsort’s Event API doc for body specification.

Sample response

200:

{
  "ok": true,
  "retry": false
}

400:

{
  "status": 400,
  "statusText": "No Content",
  "body": {
    "errCode": "bad_request",
    "docUrl": "https://docs.topsort.com/reference/errors",
    "message": "The request could not be parsed."
  }
}

429:

{
  "ok": false,
  "retry": true
}

Retryable Errors

The reportEvent function returns "retry": true if the response status code is 429 or any 5xx. This enables you to identify when it’s appropriate to retry the function call.