Add pbjs.getHighestCpmBids for getting winning bids (#755)

* Extract winning bids code into own function

* Refactor getWinningBids to support single adUnit or multiple adUnits

* Redefine api into single function and refactor getWinningBids to return undefined for unfound adUnitCodes

* Test public api function

* Use changes in filter bids PR

* Base changes off of master

* Fix lint error

* Return empty array if adUnit has no cpms > 0

src/prebid.js

@@ -154,8 +154,16 @@ function getPresetTargeting() {
   }
 }
 
-function getWinningBidTargeting() {
-  let winners = $$PREBID_GLOBAL$$._bidsReceived.map(bid => bid.adUnitCode)
+function getWinningBids(adUnitCode) {
+  // use the given adUnitCode as a filter if present or all adUnitCodes if not
+  const adUnitCodes = adUnitCode ?
+    [adUnitCode] :
+    $$PREBID_GLOBAL$$.adUnits.map(adUnit => adUnit.code);
+
+  return $$PREBID_GLOBAL$$._bidsReceived
+    .filter(bid => adUnitCodes.includes(bid.adUnitCode))
+    .filter(bid => bid.cpm > 0)
+    .map(bid => bid.adUnitCode)
     .filter(uniques)
     .map(adUnitCode => $$PREBID_GLOBAL$$._bidsReceived
       .filter(bid => bid.adUnitCode === adUnitCode ? bid : null)
@@ -166,6 +174,10 @@ function getWinningBidTargeting() {
           adserverTargeting: {},
           timeToRespond: 0
         }));
+}
+
+function getWinningBidTargeting() {
+  let winners = getWinningBids();
 
   // winning bids with deals need an hb_deal targeting key
   winners
@@ -844,4 +856,14 @@ $$PREBID_GLOBAL$$.setBidderSequence = function (order) {
   }
 };
 
+/**
+ * Get array of highest cpm bids for all adUnits, or highest cpm bid
+ * object for the given adUnit
+ * @param {string} adUnitCode - optional ad unit code
+ * @return {array} array containing highest cpm bid object(s)
+ */
+$$PREBID_GLOBAL$$.getHighestCpmBids = function (adUnitCode) {
+  return getWinningBids(adUnitCode);
+};
+
 processQue();

test/spec/unit/pbjs_api_spec.js

@@ -1262,4 +1262,32 @@ describe('Unit: Prebid Module', function () {
     });
   });
 
+  describe('getHighestCpm', () => {
+    it('returns an array of winning bid objects for each adUnit', () => {
+      const highestCpmBids = $$PREBID_GLOBAL$$.getHighestCpmBids();
+      expect(highestCpmBids.length).to.equal(2);
+      expect(highestCpmBids[0]).to.deep.equal($$PREBID_GLOBAL$$._bidsReceived[1]);
+      expect(highestCpmBids[1]).to.deep.equal($$PREBID_GLOBAL$$._bidsReceived[2]);
+    });
+
+    it('returns an array containing the highest bid object for the given adUnitCode', () => {
+      const highestCpmBids = $$PREBID_GLOBAL$$.getHighestCpmBids('/19968336/header-bid-tag-0');
+      expect(highestCpmBids.length).to.equal(1);
+      expect(highestCpmBids[0]).to.deep.equal($$PREBID_GLOBAL$$._bidsReceived[1]);
+    });
+
+    it('returns an empty array when the given adUnit is not found', () => {
+      const highestCpmBids = $$PREBID_GLOBAL$$.getHighestCpmBids('/stallone');
+      expect(highestCpmBids.length).to.equal(0);
+    });
+
+    it('returns an empty array when the given adUnit has no bids', () => {
+      $$PREBID_GLOBAL$$._bidsReceived = [$$PREBID_GLOBAL$$._bidsReceived[0]];
+      $$PREBID_GLOBAL$$._bidsReceived[0].cpm = 0;
+      const highestCpmBids = $$PREBID_GLOBAL$$.getHighestCpmBids('/19968336/header-bid-tag-0');
+      expect(highestCpmBids.length).to.equal(0);
+      resetAuction();
+    });
+  });
+
 });