Topsort SDK

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

Table of Contents

• Installation
• Usage
  • Creating an Auction
  • Reporting an Event
    • Retryable Errors
• Contributing
• License

Installation

Using npm:

npm install @topsort/sdk --save

Using yarn:

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.

Contributing

We aim to cover the entire Topsort API, and contributions are always welcome. The calling pattern is well established, making the addition of new methods relatively straightforward. For more detailed guidelines on how to contribute, please refer to our CONTRIBUTING.md.

Your help in enhancing the project is highly appreciated. Whether it’s reporting a bug, suggesting a new feature, or submitting a pull request, every bit of input helps us improve. Thank you for your support and happy coding!

License

This project is licensed under the MIT License. See the LICENSE file for more details.

Changelog

All notable changes to this project will be documented in this file.

The format is loosely based on Keep a Changelog, and this project adheres to Semantic Versioning. We follow the format used by Open Telemetry.

Version 0.3.2 (2024-09-19)

• Simplifies tsup bundling (#57)
• Adds custom error type to remove any (#58)
• Improves the events types usage by exporting interfaces from events.d.ts (#72)
• Reverts changes from (#37) (#72)

Version 0.3.1 (2024-08-15)

• Add validation to the response handler to prevent parsing of a No Content body (#44)

Version 0.3.0 (2024-08-13)

• Introduce a new way to initialize a client (#43)

As part of the new implementation, a Topsort Client that embeds all functions is now initialized by receiving a config. Also, some types have been simplified:

• TopsortAuction > Auction
• TopsortEvents > Event

Migration steps:

Auctions - Before

import { TopsortAuction, Config, reportAuction } from "@topsort/sdk";

const auction: TopsortAuction = {
    //...
};

const config: Config = {
  apiKey: "API_KEY",
};

createAuction(config, auction)
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Auctions - After

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

const auction: Auction = {
    //...
};

const config: Config = {
  apiKey: "API_KEY",
};

const topsortClient = new TopsortClient(config);

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

Events - Before

import { TopsortEvent, Config, reportEvent } from "@topsort/sdk";

const event: TopsortEvent = {
    //...
};

const config: Config = {
  apiKey: "API_KEY",
};

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

Events - After

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

const event: Event = {
    //...
};

const config: Config = {
  apiKey: "API_KEY",
};

const topsortClient = new TopsortClient(config);

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

• Fix CI/CD for release process (#38)
• Convert some parameters to optional (#36)

Version 0.2.1 (2024-08-05)

• Add support for Typescript with lower versions (#37)
• Add support for optional timeout on Config (#11)

Version 0.2.0 (2024-07-29)

• Add userAgent: string as part of Config for requests (#21)
• Add retry: boolean as part of reportEvent response (#20)

Version 0.1.0 (2024-07-19)

Added

• Initial release of the SDK (#1)
• Pull reportEvent from Analytics.js
• Add function createAuction