feat: add ctxSegments() and ctxTargetingKeyValues() for contextual targeting

[bmilekic]

Summary

Adds a contextual-classification path to the SDK: fetch the DCN's
taxonomy/category classifications for a page URL, cache them on the SDK
instance, and turn the cached response into GAM-ready targeting key-values.

What's new

SDK methods (lib/sdk.ts, lib/edge/contextual_segments.ts)

• OptableSDK.ctxSegments(url?) — POSTs to /v1beta1/contextual
  and returns ContextualSegmentsResponse with shape
  { classifications: { categories: [{ taxonomy, id, score, ... }] } }.
  url defaults to window.location.href. The response is cached on
  the instance; calling again refreshes the cache. Pass-through
  behavior (no validation / normalization), matching Targeting() at
  the edge layer.
• OptableSDK.ctxTargetingKeyValues(taxonomyKeys?) — reads the
  cached response and returns Record<string, string[]> of category
  ids grouped by taxonomy, ready for
  googletag.pubads().setTargeting(). Without a map, keys are the raw
  taxonomy values; with a map, keys are renamed and only the listed
  taxonomies are emitted (filter + rename). Ids are deduped, order
  preserved.
• initContextual is widened from boolean to
  boolean | ((response: ContextualSegmentsResponse) => void). When
  truthy, the SDK fires a pageview witness and ctxSegments() at init
  time (fire-and-forget), so the cache is populated automatically
  before any consumer reads it. When set to a callback function, the
  SDK additionally invokes the callback with the response once
  ctxSegments() resolves — useful for chaining an ad-server load
  (e.g. GAM) on the contextual response without making a second
  ctxSegments() call. The callback is not invoked if the request
  fails.

Tests (lib/sdk.test.ts, lib/test/handlers.ts)

• MSW handler for /v1beta1/contextual.
• Breaking-change tests for both new methods.
• Behavioral coverage: happy path, window.location.href default,
  empty / missing / malformed responses, categories spanning multiple
  taxonomies, cache population, default keying, rename, filter of
  unmapped taxonomies, that initContextual: true triggers a
  contextual request, and that initContextual as a function triggers
  the request and invokes the callback with the response.

Docs & demos

• README — documents the Contextual Segments API: ctxSegments()
  caching semantics, the initContextual precondition for
  ctxTargetingKeyValues(), the boolean | callback union type, the
  callback-driven loadGAM pattern, the explicit
  ctxSegments().then(loadGAM) alternative, key rename/allow-list,
  and the requirement that the URL already be classified by the DCN.
• Two new vanilla demo pages —
  demos/vanilla/targeting/ctx_segments.html.tpl and
  demos/vanilla/nocookies/targeting/ctx_segments.html.tpl — call
  ctxSegments(), render categories grouped by taxonomy with score
  bars, show the derived GAM key-values, and display the raw JSON
  response. Both pages document the initContextual callback pattern
  in the intro section and in the GAM activation section.
• Both templates registered in the Makefile demo-html target and
  linked from the Audience Targeting section of demos/index.html and
  demos/index-nocookies.html.

Files changed

11 files, +1173 / −6.

[mosherBT]

The cache here never gets cleared? Which means navigating on a site will reuse the cached contextual info? Say if we navigate on the page to a different article the contextual info never gets repopulated? We are treating the page context cache like targetingData cache but I think they need to have different behaviours.

I think we should at the very least have a ClearCache function to reload on changes.