@nextad/auction 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NextAd.js
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @nextad/auction
+
+A TypeScript library for auction compliant with OpenRTB v2.6 specification

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nextad/auction",
+  "version": "0.1.1",
+  "description": "",
+  "keywords": [],
+  "author": "Kai Miyamoto",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nextadjs/auction.git"
+  },
+  "homepage": "https://github.com/nextadjs/auction.git",
+  "devDependencies": {
+    "@nextad/faker": "^0.6.6",
+    "@types/node": "^22.10.7",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "dependencies": {
+    "iab-openrtb": "^0.4.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "import": "./dist/index.mjs",
+    "require": "./dist/index.js"
+  },
+  "scripts": {
+    "test": "vitest",
+    "build": "tsup"
+  },
+  "types": "./dist/index.d.ts"
+}

package/src/Auction.ts

@@ -0,0 +1,109 @@
+import { BidComparator } from "./BidComparator";
+import { BidFactory } from "./BidFactory";
+import {
+  AlreadyEndedAuctionException,
+  BidNotFoundException,
+} from "./exceptions";
+import type { BaseBidResponseV26, BidV26, CurrencyConversionData } from "./types";
+
+type AuctionType = "open" | "closed";
+
+type AuctionOptions = {
+  lossProcessing?: boolean;
+  currencyConversionData?: CurrencyConversionData;
+};
+
+export class Auction {
+  private losingBids: {
+    v26: BidV26[];
+  };
+  private bids: {
+    v26: BidV26[];
+  };
+
+  private itemIds: string[] = [];
+  private currencyConversionData?: CurrencyConversionData;
+  private status: AuctionType;
+  private options: AuctionOptions;
+
+  public constructor(
+    itemOrImpressionIds: string | string[],
+    options: AuctionOptions = {}
+  ) {
+    this.options = {
+      lossProcessing: true,
+      ...options,
+    };
+
+    this.bids = {
+      v26: [],
+    };
+    this.losingBids = {
+      v26: [],
+    };
+    this.currencyConversionData = options.currencyConversionData;
+    this.status = "open";
+
+    if (typeof itemOrImpressionIds === "string") {
+      this.itemIds.push(itemOrImpressionIds);
+    } else {
+      this.itemIds.push(...itemOrImpressionIds);
+    }
+  }
+
+  public getStatus(): AuctionType {
+    return this.status;
+  }
+
+  public getLosingBids(): { v26: BidV26[] } {
+    return this.losingBids;
+  }
+
+  public placeBidResponseV26(bidResponse: BaseBidResponseV26): this {
+    if (bidResponse.seatbid) {
+      this.bids.v26.push(
+        ...BidFactory.createV26Bids(bidResponse, this.itemIds)
+      );
+    }
+
+    return this;
+  }
+
+  public end(): BidV26 {
+    if (this.status !== "open") {
+      throw new AlreadyEndedAuctionException();
+    }
+
+    if (!this.bids.v26.length) {
+      throw new BidNotFoundException();
+    }
+
+    const highestBid = BidComparator.getHighestBidV26(this.bids.v26, this.options.currencyConversionData);
+
+    this.setLosingBids(highestBid);
+    this.handleLossBids();
+    this.status = "closed";
+
+    return highestBid;
+  }
+
+  private setLosingBids(winningBid: BidV26): void {
+    this.losingBids.v26.push(
+      ...this.bids.v26.filter((bid) => bid.id !== winningBid.id)
+    );
+  }
+
+  private handleLossBids(): void {
+    this.losingBids.v26.forEach((bid) => {
+      this.handleLossBid(bid);
+    });
+  }
+
+  private handleLossBid(bid: BidV26): void {
+    if (this.options.lossProcessing && bid.lurl) {
+      fetch(bid.lurl, {
+        keepalive: true,
+      });
+    }
+  }
+}

package/src/BidComparator.ts

@@ -0,0 +1,38 @@
+import type { BidV26, CurrencyConversionData } from "./types";
+
+export class BidComparator {
+  public static getHighestBidV26(
+    bids: BidV26[],
+    currencyConversionData?: CurrencyConversionData
+  ): BidV26 {
+    if (!currencyConversionData) {
+      return bids.reduce((highest, current) => {
+        const highestPrice = highest.price * 100;
+        const currentPrice = current.price * 100;
+        return currentPrice > highestPrice ? current : highest;
+      });
+    }
+
+    return bids.reduce((highest, current) => {
+      const highestPrice = this.convertPrice(highest, currencyConversionData);
+      const currentPrice = this.convertPrice(current, currencyConversionData);
+      return currentPrice > highestPrice ? current : highest;
+    });
+  }
+
+  private static convertPrice(
+    bid: BidV26, 
+    conversionData: CurrencyConversionData
+  ): number {
+    const price = bid.price;
+    const rates = conversionData.conversions[bid.ext.nextadjs.currency];
+    
+    if (!rates) {
+      return price * 100;
+    }
+
+    const targetCurrency = "USD";
+    const rate = rates[targetCurrency];
+    return price * (rate || 1) * 100;
+  }
+}

package/src/BidFactory.ts

@@ -0,0 +1,32 @@
+import type { BaseBidResponseV26, BidV26 } from "./types";
+
+export class BidFactory {
+  public static createV26Bids(
+    bidResponse: BaseBidResponseV26,
+    itemIds: string[]
+  ): BidV26[] {
+    let bids: BidV26[] = [];
+
+    if (bidResponse.seatbid) {
+      bidResponse.seatbid.forEach((seatBid) => {
+        seatBid.bid.forEach((bid) => {
+          if (itemIds.some((itemId) => bid.impid === itemId)) {
+            bids.push({
+              ...bid,
+              ext: {
+                ...bid.ext,
+                nextadjs: {
+                  openrtbVersion: "2.6",
+                  currency: bidResponse.cur || "USD",
+                  seat: seatBid.seat,
+                },
+              },
+            });
+          }
+        });
+      });
+    }
+
+    return bids;
+  }
+}

package/src/exceptions/index.ts

@@ -0,0 +1,9 @@
+export class BidNotFoundException {
+  name = "BidNotFoundException";
+  message = "Bid is not found.";
+}
+
+export class AlreadyEndedAuctionException {
+    name = "AlreadyEndedAuctionException";
+    message = "Auction is already ended.";
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './Auction';
+export * from '@/exceptions';

package/src/types/index.ts

@@ -0,0 +1,43 @@
+import type {
+  Bid as BaseBidV26,
+  BidResponse as BaseBidResponseV26,
+  SeatBid as BaseSeatBidV26,
+} from "iab-openrtb/v26";
+export type {
+  BidResponse as BaseBidResponseV26,
+  Bid as BaseBidV26,
+} from "iab-openrtb/v26";
+
+export interface BidResponseV26 extends BaseBidResponseV26 {
+  seatbid?: SeatBidV26[];
+}
+export interface SeatBidV26 extends BaseSeatBidV26 {
+  bid: BidV26[];
+}
+
+export interface BidV26 extends BaseBidV26 {
+  ext: {
+    nextadjs: {
+      openrtbVersion: "2.6";
+      seat?: string;
+      currency: string;
+    };
+  };
+}
+
+
+export interface CurrencyRates {
+  /** ISO 4217 Currency Code (Example: USD, JPY, EUR) */
+  [currency: string]: number;
+}
+
+interface ConversionRates {
+  /** convert rate of base currency */
+  [baseCurrency: string]: CurrencyRates;
+}
+
+export interface CurrencyConversionData {
+  dataAsOf: string;
+  generatedAt: string;
+  conversions: ConversionRates;
+}

package/test/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "moduleResolution": "bundler",
+    "types": ["vitest/globals"],
+    "baseUrl": "..",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["./**/*.ts"]
+}

package/test/units/Auction.test.ts

@@ -0,0 +1,176 @@
+import { openrtbFaker } from "@nextad/faker";
+import { Auction } from "@/Auction";
+import {
+  AlreadyEndedAuctionException,
+  BidNotFoundException,
+} from "@/exceptions";
+
+describe("Auction", () => {
+  it("returns highest bid from bids with specified item(impression) when auction ends", () => {
+    const sut = new Auction("impid-1");
+    const bidResponse = openrtbFaker.v26.bidResponse
+      .addBannerBid({ impid: "impid-1", price: 10 })
+      .make();
+    const bidResponse2 = openrtbFaker.v26.bidResponse
+      .addBannerBid({ impid: "impid-1", price: 20 })
+      .make();
+    sut.placeBidResponseV26(bidResponse);
+    sut.placeBidResponseV26(bidResponse2);
+
+    const result = sut.end();
+
+    expect(result.id).toBe(bidResponse2.seatbid![0].bid[0].id);
+  });
+
+  it("returns highest bid from bids with specified items(impressions) when auction ends", () => {
+    const sut = new Auction(["impid-1", "impid-2"]);
+    const bidResponse = openrtbFaker.v26.bidResponse
+      .addBannerBid({ impid: "impid-1", price: 10 })
+      .make();
+    const bidResponse2 = openrtbFaker.v26.bidResponse
+      .addBannerBid({ impid: "impid-1", price: 20 })
+      .addVideoBid({ impid: "impid-2", price: 30 })
+      .make();
+    sut.placeBidResponseV26(bidResponse);
+    sut.placeBidResponseV26(bidResponse2);
+
+    const result = sut.end();
+
+    expect(result.id).toBe(bidResponse2.seatbid![0].bid[1].id);
+  });
+
+  it("returns highest bid considering currency when auction ends", () => {
+    const sut = new Auction("impid-1", {
+      currencyConversionData: {
+        dataAsOf: "2021-01-01",
+        generatedAt: "2021-01-01",
+        conversions: {
+          JPY: {
+            USD: 0.09,
+          },
+        },
+      },
+    });
+    const bidResponse = openrtbFaker.v26.bidResponse
+      .withCurrency("JPY")
+      .addBannerBid({ impid: "impid-1", price: 10 })
+      .make();
+    const bidResponse2 = openrtbFaker.v26.bidResponse
+      .withCurrency("USD")
+      .addBannerBid({ impid: "impid-1", price: 5 })
+      .make();
+    sut.placeBidResponseV26(bidResponse);
+    sut.placeBidResponseV26(bidResponse2);
+
+    const result = sut.end();
+
+    expect(result.id).toBe(bidResponse2.seatbid![0].bid[0].id);
+  });
+
+  it("throws error when attempting to end auction without bids", () => {
+    const sut = new Auction("impid-1");
+
+    expect(() => sut.end()).toThrow(BidNotFoundException);
+  });
+  it("returns losing bids when auction ends", () => {
+    const sut = new Auction(["impid-1", "impid-2"]);
+    const bidResponse = openrtbFaker.v26.bidResponse
+      .addBannerBid({
+        impid: "impid-1",
+        price: 10,
+      })
+      .addBannerBid({
+        impid: "impid-2",
+        price: 20,
+      })
+      .make();
+    sut.placeBidResponseV26(bidResponse);
+
+    sut.end();
+
+    const losingBids = sut.getLosingBids();
+    expect(losingBids.v26.length).toBe(1);
+    expect(losingBids.v26[0].id).toBe(bidResponse.seatbid![0].bid[0].id);
+  });
+
+  it("throws error when attempting to already ended auction", () => {
+    const sut = new Auction("impid-1");
+    const bidResponse = openrtbFaker.v26.bidResponse
+      .addBannerBid({ impid: "impid-1", price: 10 })
+      .make();
+    sut.placeBidResponseV26(bidResponse);
+    sut.end();
+
+    expect(() => sut.end()).toThrow(AlreadyEndedAuctionException);
+  });
+
+  it("sends loss notification when bid contains loss notice url", () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    const sut = new Auction(["impid-1", "impid-2"]);
+    const bidResponse = openrtbFaker.v26.bidResponse
+      .addBannerBid({
+        impid: "impid-1",
+        price: 10,
+        lurl: "https://example.com/lurl",
+      })
+      .addBannerBid({
+        impid: "impid-2",
+        price: 20,
+      })
+      .make();
+    sut.placeBidResponseV26(bidResponse);
+
+    sut.end();
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    expect(fetchMock).toHaveBeenCalledWith("https://example.com/lurl", {
+      keepalive: true,
+    });
+  });
+
+  it("does not send loss notification when bid does not contain loss notice url", () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    const sut = new Auction(["impid-1", "impid-2"]);
+    const bidResponse = openrtbFaker.v26.bidResponse
+      .addBannerBid({
+        impid: "impid-1",
+        price: 10,
+      })
+      .addBannerBid({
+        impid: "impid-2",
+        price: 20,
+      })
+      .make();
+    sut.placeBidResponseV26(bidResponse);
+
+    sut.end();
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("does not send loss notification when loss processing is specified as false", () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    const sut = new Auction(["impid-1", "impid-2"], {
+      lossProcessing: false,
+    });
+    const bidResponse = openrtbFaker.v26.bidResponse
+      .addBannerBid({
+        impid: "impid-1",
+        price: 10,
+        lurl: "https://example.com/lurl",
+      })
+      .addBannerBid({
+        impid: "impid-2",
+        price: 20,
+      })
+      .make();
+    sut.placeBidResponseV26(bidResponse);
+
+    sut.end();
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "lib": ["es2022", "esnext.disposable", "dom"],
+
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "allowJs": true,
+
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "preserveConstEnums": true,
+    "noEmit": true,
+
+    "skipLibCheck": true,
+    "strict": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  format: ["esm", "cjs"],
+  clean: true,
+  minify: true,
+  dts: true,
+  entry: ["src/index.ts"],
+});

package/vitest.config.ts

@@ -0,0 +1,14 @@
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { defineConfig } from "vitest/config";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+
+export default defineConfig({
+  test: {
+    globals: true,
+    alias: {
+      "@": path.resolve(__dirname, "src"),
+    },
+  },
+});