Optimizely Data Platform

export const ODP_API_HOST = process.env.OPTIMIZELY_ODP_API_HOST ?? "https://api.zaius.com";
export const ODP_API_KEY  = process.env.OPTIMIZELY_ODP_API_KEY  ?? "";

// Look up membership by fs_user_id: OdpSetup stitches the FX visitor id (optimizelyEndUserId)
// into ODP as fs_user_id, so the profile lives under that identifier - NOT vuid. Querying by
// vuid here returns an empty customer and no audiences ever resolve.
const SEGMENT_QUERY = `
  query GetSegments($userId: String!, $segmentFilter: [String!]!) {
    customer(fs_user_id: $userId) {
      audiences(subset: $segmentFilter) {
        edges { node { name state } }
      }
    }
  }
`;

// Lists every audience `name` defined on the ODP account. Used to build the "all audiences"
// subset for the verification panel - ODP's `audiences(subset:)` requires an explicit list.
const ALL_AUDIENCES_QUERY = `{ audiences { edges { node { name } } } }`;

async function listAudienceNames(fresh = false): Promise<string[]> {
  if (!ODP_API_KEY) return [];
  try {
    const res = await fetch(`${ODP_API_HOST}/v3/graphql`, {
      method: "POST",
      headers: { "Content-Type": "application/json", "x-api-key": ODP_API_KEY },
      body: JSON.stringify({ query: ALL_AUDIENCES_QUERY }),
      ...(fresh ? { cache: "no-store" as const } : { next: { revalidate: 3600 } }),
    });
    if (!res.ok) return [];
    const data = await res.json();
    return (data.data?.audiences?.edges ?? []).map((e: { node: { name: string } }) => e.node.name);
  } catch {
    return [];
  }
}

// Queries ODP for which of `subset` the visitor currently qualifies for. `fresh` bypasses the
// 5-min fetch cache (used by the live verification panel, which must reflect current state).
async function querySegments(userId: string, subset: string[], fresh: boolean): Promise<string[]> {
  if (!ODP_API_KEY || subset.length === 0) return [];
  try {
    const res = await fetch(`${ODP_API_HOST}/v3/graphql`, {
      method: "POST",
      headers: { "Content-Type": "application/json", "x-api-key": ODP_API_KEY },
      body: JSON.stringify({ query: SEGMENT_QUERY, variables: { userId, segmentFilter: subset } }),
      ...(fresh ? { cache: "no-store" as const } : { next: { revalidate: 300 } }),
    });
    if (!res.ok) return [];
    const data = await res.json();
    return (
      (data.data?.customer?.audiences?.edges ?? [])
        .filter((e: { node: { state: string } }) => e.node.state === "qualified")
        .map((e: { node: { name: string } }) => e.node.name)
    );
  } catch {
    return [];
  }
}

// Production path: only asks ODP about the segments in ODP_SEGMENT_TO_VARIATION (the ones that
// actually drive a homepage variation).
export async function queryOdpSegments(userId: string, fresh = false): Promise<string[]> {
  return querySegments(userId, Object.keys(ODP_SEGMENT_TO_VARIATION), fresh);
}

// Verification path: every ODP audience the visitor qualifies for, whether mapped or not. Lets
// the switcher panel show the full picture (e.g. "in active_visitors, just not a mapped one").
export async function queryAllQualifiedSegments(userId: string, fresh = false): Promise<string[]> {
  const all = await listAudienceNames(fresh);
  return querySegments(userId, all, fresh);
}

// The explicit contract between ODP audience identifiers and CMS variation names.
// This is the only place to update when either side renames something. Keys are the exact
// ODP audience `name` (case-sensitive - list them with `npx tsx scripts/maintenance/test-odp.ts`);
// values are the CMS variation names, which must match the homepage CMS Variations exactly.
//
// Today the two sides are named differently (`business_banking_customer` -> `business`), so an
// explicit value is needed. When they are renamed to match (audience `business` -> variation
// `business`), you can leave the value blank ("") - resolveVariationKey falls back to the
// audience name itself, so identical naming needs no paired value. Either style works.
//
// The homepage in the CMS carries variations for returning, business, personal, mortgages and
// investments. Every one except investments has a backing ODP audience or segment below; the
// investments variation is seeded in the CMS but never selected until an audience exists. That
// "half-configured" state is intentional - create the audience in ODP and add its identifier
// here to light it up.
export const ODP_SEGMENT_TO_VARIATION: Record<string, string> = {
  // Identity / lifecycle (cross-session). Qualifying on mb_customer_identified (has_email=true)
  // means we recognise a known customer on a later visit - serve the welcome-back experience.
  known_customers: "returning",
  // Batch audiences (recompute on ODP's schedule - fine for returning-visitor personalization).
  business_banking_customer: "business",
  personal_banking_customers: "personal",
  // Realtime segments (evaluate on the live event stream - qualify within a session). Named
  // differently from the batch audiences above, so both are listed and either one resolves.
  business_visitors: "business",
  mortgage_visitors: "mortgages",
  // Still unmapped - no backing audience/segment yet:
  //   "<investor-audience>": "investments",
};

// Precedence when a visitor qualifies for several mapped audiences at once. Identity/lifecycle
// wins over browsing-persona, so a known customer who is also browsing business still gets the
// welcome-back experience. Any mapped segment not listed here is considered after these, in the
// order ODP returned it.
const VARIATION_PRIORITY = [
  "known_customers",
  "business_visitors",
  "business_banking_customer",
  "mortgage_visitors",
  "personal_banking_customers",
] as const;

// Resolves a qualifying ODP audience to a CMS variation key, honouring VARIATION_PRIORITY first.
// A blank map value means "the audience and variation share a name" - fall back to the audience
// name itself. The `map` parameter defaults to the module map so the logic can be unit-tested.
export function resolveVariationKey(
  segments: string[],
  map: Record<string, string> = ODP_SEGMENT_TO_VARIATION,
): string | undefined {
  for (const name of VARIATION_PRIORITY) {
    if (segments.includes(name) && name in map) return map[name] || name;
  }
  for (const segment of segments) {
    if (segment in map) return map[segment] || segment;
  }
}

"use client";

import { usePathname } from "next/navigation";
import { useEffect } from "react";

import "@/lib/tracking/destinations/odp";
import { readCookie } from "@/lib/tracking/cookies";
import { VISITOR_ID_COOKIE } from "@/lib/optimizely/cookieNames";

export default function OdpSetup() {
  const pathname = usePathname();

  // Link the FX visitor ID to ODP once on mount so server-side segment
  // queries can use optimizelyEndUserId via the fs_user_id identifier.
  useEffect(() => {
    const fsUserId = readCookie(VISITOR_ID_COOKIE);
    if (fsUserId) window.zaius?.entity("customer", { fs_user_id: fsUserId });
  }, []);

  // Fire a pageview so ODP can qualify the visitor for pageview-based real-time segments.
  // Pass ONLY the fs_user_id identifier - do NOT pass a `page` field: the ODP Web SDK
  // auto-parses the page URL from the browser context and populates the normalized
  // "Page > URL" entity that segment rules (e.g. "Page > URL contains business") read.
  // Passing `page` manually suppresses that normalization, leaving "Page > URL" empty so
  // URL-conditioned segments match nobody. fs_user_id is stitched to the anonymous vuid via
  // the entity() call above, so the pageview is attributed to the unified customer profile.
  useEffect(() => {
    const fsUserId = readCookie(VISITOR_ID_COOKIE);
    window.zaius?.event("pageview", fsUserId ? { fs_user_id: fsUserId } : undefined);
  }, [pathname]);

  return null;
}

import "server-only";
import { cache } from "react";
import {
  createInstance,
  createStaticProjectConfigManager,
  createForwardingEventProcessor,
  createLogger,
  createOdpManager,
  eventDispatcher,
  OptimizelyDecideOption,
  ERROR,
  type Client,
} from "@optimizely/optimizely-sdk";
import { fetchDatafile } from "./datafile";
import type { FxDecision } from "./experimentation";
import { getVisitorContext } from "./visitor";

// FX with its native ODP integration switched on, so an FX audience can target an
// ODP segment directly (ODP_SEGMENT conditions) instead of going through the
// hand-rolled ODP_SEGMENT_TO_VARIATION map in odp.ts.
//
// This is a PARALLEL factory on purpose. getOptimizelyClient() in experimentation.ts
// and getOptimizelyUser() in user.ts are untouched, so middleware, every existing
// server component and FxBucketingEvent keep behaving exactly as before.
//
// WHERE THIS MAY BE USED: route handlers, the dynamic homepage branch, /demo/* pages.
// NOT in src/middleware.ts - fetchQualifiedSegments() is an awaited HTTPS round trip
// to ODP, and middleware runs on every request including prefetches under a 3s budget.
// NOT in the browser - the zaius tag already owns browser-side ODP identity, and a
// second consumer would create two sources of truth for fs_user_id.
//
// The ODP API key and host come from the FX DATAFILE (the `integrations` entry written
// when ODP is enabled under FX project Settings -> Integrations), not from env vars, so
// no new credential is needed. With the integration off, fetchQualifiedSegments()
// simply resolves false and decide() still works normally.

export const getOdpAwareClient = cache(async function getOdpAwareClient(): Promise<Client | null> {
  const datafileText = await fetchDatafile();
  if (!datafileText) return null;
  return (
    createInstance({
      projectConfigManager: createStaticProjectConfigManager({ datafile: datafileText }),
      logger: createLogger({ level: ERROR }),
      eventProcessor: createForwardingEventProcessor(eventDispatcher),
      odpManager: createOdpManager({
        // Mirrors the 5-minute posture odp.ts already uses for segment reads.
        segmentsCacheTimeout: 300_000,
        // Hard ceiling: a slow ODP must never stall a render.
        segmentsApiTimeout: 2_000,
      }),
    }) ?? null
  );
});

export type SegmentAwareUser = {
  userId: string;
  /** ODP audiences this visitor qualifies for. Empty when the integration is off. */
  qualifiedSegments: string[];
  isQualifiedFor(segment: string): boolean;
  /** Impression-suppressed by default, matching getDecision() in experimentation.ts. */
  decide(flagKey: string, options?: OptimizelyDecideOption[]): FxDecision;
};

export const getSegmentAwareUser = cache(async function getSegmentAwareUser(): Promise<SegmentAwareUser | null> {
  const [client, { userId, attributes, bucketingId }] = await Promise.all([
    getOdpAwareClient(),
    getVisitorContext(),
  ]);
  if (!client || userId === "anonymous") return null;

  const ctx = client.createUserContext(userId, attributes);
  if (!ctx) return null;
  if (bucketingId) ctx.setAttribute("$opt_bucketing_id", bucketingId);

  // Resolves false when the ODP integration is off or the call fails. Either way we
  // fall through to an empty segment list rather than null, so callers need no
  // special-case branch.
  await ctx.fetchQualifiedSegments().catch(() => false);

  return {
    userId,
    qualifiedSegments: ctx.qualifiedSegments ?? [],
    isQualifiedFor: (segment: string) => ctx.isQualifiedFor(segment),
    decide(flagKey: string, options = [OptimizelyDecideOption.DISABLE_DECISION_EVENT]) {
      const d = ctx.decide(flagKey, options);
      return {
        flagKey,
        enabled: d.enabled,
        variationKey: d.variationKey,
        variables: d.variables as Record<string, unknown>,
        reasons: d.reasons,
      };
    },
  };
});