gpt: add targeting, contextual and EID-derived secure signal helpers

[mosherBT]

Adds three methods to the GPT addon, covering googletag calls that integrations currently have to write themselves.

What's added

setGPTTargeting(keyValues) — writes page-level custom targeting via googletag.setConfig(), which merges the supplied keys into existing page-level targeting rather than replacing it. Safe to call alongside a publisher's own targeting and more than once with different keys. Values may be a string or a list of strings.

setGPTContextualTargeting(taxonomyKeys?, options?) — pushes the contextual key-values already cached on the instance to pubads().setTargeting(). Both arguments are forwarded to ctxTargetingKeyValues() unchanged.

This method deliberately does not fetch. Reading the cached response means it can be driven straight from the initContextual callback, which InitConfig already supports for exactly this purpose, without issuing a second ctxSegments() request:

const sdk = new OptableSDK({
  host: "dcn.customer.com",
  site: "my-site",
  initContextual: () => sdk.setGPTContextualTargeting(),
});

installGPTSecureSignalsFromEIDs(eids, filter?) — derives { provider, id } pairs from ORTB2 EIDs and registers them through the existing installGPTSecureSignals(), so a targeting response can be handed over directly:

sdk.installGPTSecureSignalsFromEIDs(eids, { sources: ["uidapi.com"] });

sources, inserters and matchers are allow-lists over the corresponding EID fields. An omitted or empty list places no constraint on that field, matching the matcherFilter convention in the RTD module (lib/core/prebid/rtd.ts:312) rather than filtering everything out.

A provider is registered at most once per page load. GPT keeps one collector function per provider id, so re-registering the same provider would install a duplicate collector. This means a refreshed token does not replace an already-registered signal — noted in the addon docs.

Notes

• All three methods queue on googletag.cmd and create window.googletag if absent, so they are safe to call before GPT has loaded.
• Both new googletag calls are wrapped so a failure cannot propagate into the host page, consistent with installGPTEventListeners.
• The installGPTEventListeners and installGPTSecureSignals declarations were typed () => void despite both taking arguments. Corrected — type-only, no behaviour change.
• No existing method changes behaviour; the addition is additive.

Docs

New lib/addons/gpt.md covering all five addon methods, filtering rules, contextual wiring and a full example, following the abTestAssignment.md layout. Linked from the GAM360 section of the main README.

Tests

11 new cases in lib/addons/gpt.test.js covering targeting merge behaviour, contextual push and argument forwarding, secure-signal derivation, each filter dimension, empty-list semantics, once-per-provider registration, and the no-op paths.

Suite passes at 21 suites / 338 tests. (npx jest also picks up stale copies under .claude/worktrees/; those 4 failures pre-exist on master and are unrelated.)

[mosherBT]

Closing this will reopen when ready to test and prepare the PR