Add pgamdirect Analytics Adapter (#14778)

* Add pgamdirect Analytics Adapter

Companion to modules/pgamdirectBidAdapter.ts (merged #14763).
Publishers install this alongside the bid adapter to forward auction
telemetry to the PGAM Direct SSP backend.

Forwards four Prebid events, deliberately narrow:
  AUCTION_END           — competitor CPMs seen in the auction
  BID_WON               — Prebid-layer winner + price
  AD_RENDER_SUCCEEDED   — client-confirmed impression
  AD_RENDER_FAILED      — with reason (exception / timeout / etc)

The value add over a server-side-only ledger: client-confirmed render
vs. "RTB said we won", plus visibility into what other bidders priced
the same auction at (we own server-side data for our own DSP calls,
but not for the ones other SSPs made through the same Prebid wrapper).

Payload is normalised into a small fixed shape before POST — we
deliberately drop the raw Prebid event args, which carry full FPD /
user.eids / custom bidder params that we don't need and shouldn't
exfiltrate. Sink: https://app.pgammedia.com/api/analytics-events (one
POST per event; content-type text/plain to keep CORS simple).

Config:
  pbjs.enableAnalytics({
    provider: 'pgamdirect',
    options: {
      orgId: '<pgam org id>',           // required
      endpoint: 'https://...'            // optional override
    }
  });

GVL ID 1353 (PGAM Media LLC, same as the bid adapter).

Tests: 12 covering registration, orgId validation, and the pure
normalise transform across all 4 forwarded event types (including
the 20-entry bidders_seen cap and filter-out of bidders with no
code). Event-emission path is not covered in this spec because the
sinon mock + AnalyticsAdapter async queue interact oddly in the
test harness — we export normalise() directly so the transform is
verifiable without the full event pipeline. The ajax call itself is
covered by upstream AnalyticsAdapter base-class tests.

* pgamdirectAnalytics: address Codex review on #14778

Two P1s flagged by Codex on the initial commit:

1. ad_unit_code semantic inconsistency

Original code pulled ad_unit_code from args.adUnitCode on BID_WON
but from args.adId on AD_RENDER_*, so the same field represented
different identifiers across event types. In auctions with multiple
ad units (or repeated wins from the same bidder), this prevented
reliable win → render reconciliation and could misattribute render
outcomes.

Fix: render events now read ad_unit_code from args.bid.adUnitCode
(stable across the BID_WON ↔ AD_RENDER_* join for the same slot).
adId moves to its own field `ad_id` so per-bid traceability is
preserved. Type definition updated with a comment explaining the
split so future contributors don't re-conflate them.

2. Missing fetch keepalive

Prebid AGENTS.md §71 requires low-priority telemetry calls to set
fetch keepalive. Without it, BID_WON + AD_RENDER_* events emitted
near page unload get dropped before reaching the endpoint — and
those are exactly the events that fire in that window.

Added `keepalive: true` to the ajax call. Prebid's ajax helper
already supports the flag (src/ajax.ts option); no adapter-side
polyfill needed.

Tests: +1 spec case covering "missing bid object on AD_RENDER_*
still captures ad_id cleanly." Existing render-event assertions
updated to verify the ad_unit_code-vs-ad_id split explicitly.
13/13 pass (was 12).

Author: mastap150

modules/pgamdirectAnalyticsAdapter.ts

@@ -0,0 +1,251 @@
+/**
+ * pgamdirect Analytics Adapter.
+ *
+ * Publishers include this module alongside `pgamdirectBidAdapter` to
+ * forward Prebid auction telemetry to the PGAM Direct SSP backend.
+ * Companion to the server-side bid-outcomes ledger we maintain from
+ * the bidder — this module gives us CLIENT-confirmed signals that
+ * the RTB path can't see:
+ *
+ *   AUCTION_END   — final state of every auction (who we competed
+ *                    against, at what prices). Lets us see
+ *                    competitor CPMs without needing their
+ *                    reports.
+ *   BID_WON       — which bidder won in the Prebid layer and what
+ *                    they paid. Critical for our reconciliation
+ *                    because a server-side win notice doesn't tell
+ *                    us if the publisher actually rendered the ad.
+ *   AD_RENDER_SUCCEEDED / AD_RENDER_FAILED — client-confirmed
+ *                    impression. Feeds the discrepancy reconciler
+ *                    so we can distinguish "bidder said we won" from
+ *                    "user actually saw the ad."
+ *
+ * Configuration (publisher-side):
+ *
+ *   pbjs.enableAnalytics({
+ *     provider: 'pgamdirect',
+ *     options: {
+ *       orgId: '<your pgam org id>'          // REQUIRED
+ *       // endpoint: 'https://...custom...'   // optional override
+ *     }
+ *   });
+ *
+ * GVL ID: 1353 (same as the bid adapter, PGAM Media LLC).
+ */
+
+import adapter from '../libraries/analyticsAdapter/AnalyticsAdapter.js';
+import { EVENTS } from '../src/constants.js';
+import adapterManager from '../src/adapterManager.js';
+import { ajax } from '../src/ajax.js';
+import { logError, logMessage } from '../src/utils.js';
+
+const ANALYTICS_CODE = 'pgamdirect';
+const GVLID = 1353;
+const DEFAULT_ENDPOINT =
+  'https://app.pgammedia.com/api/analytics-events';
+
+// Which events we forward. Deliberately narrow: the four that carry
+// reconciliation-grade signal. Adding more here increases the
+// per-auction payload size without materially improving our models.
+const FORWARDED_EVENTS: readonly string[] = [
+  EVENTS.AUCTION_END,
+  EVENTS.BID_WON,
+  EVENTS.AD_RENDER_SUCCEEDED,
+  EVENTS.AD_RENDER_FAILED,
+];
+
+interface PgamAnalyticsOptions {
+  orgId?: string;
+  endpoint?: string;
+}
+
+let orgId: string | null = null;
+let endpoint = DEFAULT_ENDPOINT;
+
+const pgamdirectAnalytics = Object.assign(
+  adapter({ url: DEFAULT_ENDPOINT, analyticsType: 'endpoint' }),
+  {
+    /**
+     * Called by the AnalyticsAdapter base class on every tracked
+     * event (via enqueue → track). We filter to our forwarded set,
+     * normalise to a compact shape, and POST event-by-event.
+     *
+     * We deliberately do NOT forward the raw Prebid event args —
+     * they carry a lot of site-private data (full FPD blobs,
+     * user.eids, custom bidder params) that we don't need and
+     * shouldn't exfiltrate.
+     */
+    track({ eventType, args }: { eventType: string; args?: unknown }) {
+      if (!orgId) return;
+      if (!FORWARDED_EVENTS.includes(eventType)) return;
+      try {
+        const normalised = normalise(eventType, args);
+        const body = JSON.stringify({ org_id: orgId, event: normalised });
+        // Content-type 'text/plain' keeps the POST CORS-simple (no
+        // preflight). Our analytics sink parses text/plain as JSON
+        // deliberately.
+        //
+        // keepalive=true per Prebid AGENTS.md guidance for low-
+        // priority telemetry: without it, events emitted near page
+        // navigation / unload get dropped before the XHR lands. The
+        // most valuable events (BID_WON, AD_RENDER_*) fire exactly
+        // in the unload window, so this directly improves delivery.
+        ajax(endpoint, undefined, body, {
+          method: 'POST',
+          withCredentials: false,
+          contentType: 'text/plain',
+          keepalive: true,
+        });
+      } catch (err) {
+        logError('[pgamdirectAnalytics] track failed', err);
+      }
+    },
+  },
+);
+
+// Minimal event shape we extract from each Prebid event.
+//
+// Note on ad_unit_code vs ad_id: they identify different things and
+// must be kept separate so downstream reconciliation can join a
+// BID_WON to its AD_RENDER_* event reliably.
+//
+//   ad_unit_code — the publisher's slot identifier (same on BID_WON
+//                  and on the subsequent AD_RENDER_SUCCEEDED for that
+//                  slot). Stable per-adunit; reused across auctions
+//                  when the same slot refreshes.
+//   ad_id        — Prebid's per-bid adId (unique per bid response,
+//                  changes every auction). Present on the render
+//                  events so we can tie a specific bid's render
+//                  outcome back to the BID_WON that preceded it.
+//
+// Earlier revision misused adId as ad_unit_code on the render events
+// (flagged by Codex review on #14778); this split fixes
+// cross-event reconciliation.
+interface NormalisedEvent {
+  t: string;
+  ts: number;
+  auction_id?: string;
+  bidder?: string;
+  cpm?: number;
+  currency?: string;
+  ad_unit_code?: string;
+  ad_id?: string;
+  creative_id?: string;
+  media_type?: string;
+  size?: string;
+  bidders_seen?: Array<{
+    bidder: string;
+    cpm?: number;
+    media_type?: string;
+    size?: string;
+  }>;
+  render_fail_reason?: string;
+}
+
+// Exported for unit testing — keeps the pure transform verifiable
+// without needing the full Prebid events harness.
+export function normalise(eventType: string, rawArgs: unknown): NormalisedEvent {
+  const a = (rawArgs ?? {}) as Record<string, unknown>;
+  const base: NormalisedEvent = {
+    t: eventType,
+    ts: Date.now(),
+    auction_id: typeof a.auctionId === 'string' ? a.auctionId : undefined,
+  };
+
+  switch (eventType) {
+    case EVENTS.BID_WON:
+      return {
+        ...base,
+        bidder: typeof a.bidderCode === 'string' ? a.bidderCode : undefined,
+        cpm: typeof a.cpm === 'number' ? a.cpm : undefined,
+        currency: typeof a.currency === 'string' ? a.currency : undefined,
+        ad_unit_code: typeof a.adUnitCode === 'string' ? a.adUnitCode : undefined,
+        creative_id: typeof a.creativeId === 'string' ? a.creativeId : undefined,
+        media_type: typeof a.mediaType === 'string' ? a.mediaType : undefined,
+        size: typeof a.size === 'string' ? a.size : undefined,
+      };
+
+    case EVENTS.AUCTION_END: {
+      const bids = Array.isArray(a.bidsReceived)
+        ? (a.bidsReceived as Array<Record<string, unknown>>)
+        : [];
+      return {
+        ...base,
+        bidders_seen: bids
+          .slice(0, 20) // hard cap
+          .map((b) => ({
+            bidder: typeof b.bidderCode === 'string' ? b.bidderCode : '',
+            cpm: typeof b.cpm === 'number' ? b.cpm : undefined,
+            media_type: typeof b.mediaType === 'string' ? b.mediaType : undefined,
+            size: typeof b.size === 'string' ? b.size : undefined,
+          }))
+          .filter((b) => b.bidder),
+      };
+    }
+
+    case EVENTS.AD_RENDER_SUCCEEDED: {
+      // Render events carry the winning bid nested under args.bid;
+      // extract adUnitCode from THERE (stable across BID_WON ↔
+      // AD_RENDER_* joins). adId goes into its own field for
+      // per-bid traceability.
+      const bid =
+        typeof a.bid === 'object' && a.bid
+          ? (a.bid as Record<string, unknown>)
+          : null;
+      return {
+        ...base,
+        bidder: bid && typeof bid.bidderCode === 'string' ? bid.bidderCode : undefined,
+        ad_unit_code: bid && typeof bid.adUnitCode === 'string' ? bid.adUnitCode : undefined,
+        ad_id: typeof a.adId === 'string' ? a.adId : undefined,
+      };
+    }
+
+    case EVENTS.AD_RENDER_FAILED: {
+      const bid =
+        typeof a.bid === 'object' && a.bid
+          ? (a.bid as Record<string, unknown>)
+          : null;
+      return {
+        ...base,
+        render_fail_reason: typeof a.reason === 'string' ? a.reason : 'unknown',
+        ad_unit_code: bid && typeof bid.adUnitCode === 'string' ? bid.adUnitCode : undefined,
+        ad_id: typeof a.adId === 'string' ? a.adId : undefined,
+      };
+    }
+
+    default:
+      return base;
+  }
+}
+
+// Intercept enableAnalytics to capture orgId + endpoint out of the
+// provider config. Pattern copied from
+// modules/AsteriobidPbmAnalyticsAdapter.js and other TS adapters.
+(pgamdirectAnalytics as unknown as Record<string, unknown>)
+  .originEnableAnalytics = pgamdirectAnalytics.enableAnalytics;
+pgamdirectAnalytics.enableAnalytics = function (config: {
+  options?: PgamAnalyticsOptions;
+}) {
+  const opts = config?.options ?? {};
+  if (!opts.orgId || typeof opts.orgId !== 'string') {
+    logError('[pgamdirectAnalytics] options.orgId is required');
+    return;
+  }
+  orgId = opts.orgId;
+  if (typeof opts.endpoint === 'string' && opts.endpoint) {
+    endpoint = opts.endpoint;
+  }
+  logMessage(`[pgamdirectAnalytics] enabled for orgId=${orgId}`);
+  (
+    (pgamdirectAnalytics as unknown as Record<string, unknown>)
+      .originEnableAnalytics as (c: unknown) => void
+  ).call(pgamdirectAnalytics, config);
+};
+
+adapterManager.registerAnalyticsAdapter({
+  adapter: pgamdirectAnalytics,
+  code: ANALYTICS_CODE,
+  gvlid: GVLID,
+});
+
+export default pgamdirectAnalytics;