@optable/web-sdk 0.59.0 → 0.61.0

package/lib/dist/addons/uid2-refresh.js

@@ -0,0 +1,119 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { AgentType } from "iab-adcom";
+import { LocalStorage } from "../core/storage";
+import { sendTargetingUpdateEvent } from "../core/events/cache-refresh";
+const UID2_REFRESH_ENDPOINT = "https://prod.uidapi.com/v2/token/refresh";
+function isUid2RefData(body) {
+    const b = body;
+    return (!!b &&
+        typeof b.advertising_token === "string" &&
+        typeof b.refresh_token === "string" &&
+        typeof b.refresh_response_key === "string" &&
+        typeof b.refresh_from === "number" &&
+        typeof b.refresh_expires === "number" &&
+        typeof b.identity_expires === "number");
+}
+// Refresh responses are base64(12-byte nonce || AES-GCM ciphertext), keyed by
+// the refresh_response_key issued alongside the refresh token.
+//
+// A response that cannot be decoded or decrypted throws; error policy stays
+// with the caller.
+function refreshUid2Token(refreshToken_1, refreshResponseKey_1) {
+    return __awaiter(this, arguments, void 0, function* (refreshToken, refreshResponseKey, endpoint = UID2_REFRESH_ENDPOINT) {
+        const response = yield fetch(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "text/plain" },
+            body: refreshToken,
+        });
+        if (!response.ok) {
+            // Error responses (400/401) are unencrypted JSON carrying a documented
+            // status (client_error, invalid_token, expired_token, unauthorized) and a
+            // free-form message.
+            let reason = `HTTP ${response.status}`;
+            let message;
+            try {
+                const body = JSON.parse(yield response.text());
+                if (typeof (body === null || body === void 0 ? void 0 : body.status) === "string") {
+                    reason = body.status;
+                }
+                if (typeof (body === null || body === void 0 ? void 0 : body.message) === "string") {
+                    message = body.message;
+                }
+            }
+            catch (_a) {
+                // Non-JSON error body; keep the HTTP status as the reason.
+            }
+            return { status: "error", reason, message };
+        }
+        const encrypted = yield response.text();
+        const encryptedBytes = Uint8Array.from(atob(encrypted), (c) => c.charCodeAt(0));
+        const keyBytes = Uint8Array.from(atob(refreshResponseKey), (c) => c.charCodeAt(0));
+        const nonce = encryptedBytes.slice(0, 12);
+        const ciphertext = encryptedBytes.slice(12);
+        const cryptoKey = yield crypto.subtle.importKey("raw", keyBytes, { name: "AES-GCM" }, false, ["decrypt"]);
+        const decrypted = yield crypto.subtle.decrypt({ name: "AES-GCM", iv: nonce }, cryptoKey, ciphertext);
+        const parsed = JSON.parse(new TextDecoder().decode(decrypted));
+        if ((parsed === null || parsed === void 0 ? void 0 : parsed.status) === "optout") {
+            return { status: "optout" };
+        }
+        if ((parsed === null || parsed === void 0 ? void 0 : parsed.status) !== "success") {
+            return { status: "error", reason: `operator status "${parsed === null || parsed === void 0 ? void 0 : parsed.status}"` };
+        }
+        if (!isUid2RefData(parsed.body)) {
+            return { status: "error", reason: "malformed response body" };
+        }
+        return { status: "success", body: parsed.body };
+    });
+}
+// Operator rejections that mean the cached identity is definitively dead.
+const EVICTION_REASONS = new Set(["invalid_token", "expired_token"]);
+/**
+ * Applies a refresh outcome to the targeting cache: success rewrites the
+ * matching EID in place, optout and definitive rejections evict it, any other
+ * error leaves the cache untouched for retry on the next page load. Sends the
+ * targeting change event after each write.
+ */
+function applyUid2Refresh(config, source, result) {
+    if (result.status === "error" && !EVICTION_REASONS.has(result.reason)) {
+        return;
+    }
+    const updated = new LocalStorage(config).updateTargeting((cached) => {
+        var _a, _b;
+        const eids = (_b = (_a = cached === null || cached === void 0 ? void 0 : cached.ortb2) === null || _a === void 0 ? void 0 : _a.user) === null || _b === void 0 ? void 0 : _b.eids;
+        // If cache does not exist don't try to set.
+        if (!eids) {
+            return false;
+        }
+        const idx = eids.findIndex((e) => e.source === source);
+        if (idx === -1) {
+            return false;
+        }
+        if (result.status === "success") {
+            eids[idx].uids = [{ atype: AgentType.PERSON_BASED, id: result.body.advertising_token }];
+            eids[idx]._ref = {
+                advertising_token: result.body.advertising_token,
+                refresh_token: result.body.refresh_token,
+                refresh_response_key: result.body.refresh_response_key,
+                refresh_from: result.body.refresh_from,
+                refresh_expires: result.body.refresh_expires,
+                identity_expires: result.body.identity_expires,
+            };
+        }
+        else {
+            eids.splice(idx, 1);
+        }
+        return true;
+    });
+    if (updated) {
+        sendTargetingUpdateEvent(config, updated);
+    }
+}
+export { refreshUid2Token, applyUid2Refresh, UID2_REFRESH_ENDPOINT };

package/lib/dist/build.json

@@ -1,3 +1,3 @@
 {
-    "version": "v0.59.0"
+    "version": "v0.61.0"
 }

package/lib/dist/config.d.ts

@@ -38,6 +38,7 @@ type InitConfig = {
     abTests?: ABTestConfig[];
     additionalTargetingSignals?: TargetingSignals;
     forwardSignals?: boolean;
+    ois?: boolean;
     timeout?: string;
     insecure?: boolean;
     pageContext?: PageContextConfig | boolean;
@@ -62,6 +63,7 @@ type ResolvedConfig = {
     abTests?: ABTestConfig[];
     additionalTargetingSignals?: TargetingSignals;
     forwardSignals?: boolean;
+    ois?: boolean;
     timeout?: string;
     insecure?: boolean;
 };

package/lib/dist/config.js

@@ -34,6 +34,7 @@ function getConfig(init) {
         abTests: init.abTests,
         additionalTargetingSignals: init.additionalTargetingSignals,
         forwardSignals: init.forwardSignals,
+        ois: init.ois,
         timeout: init.timeout,
         insecure: init.insecure,
     };

package/lib/dist/core/flags.d.ts

@@ -1,6 +1,8 @@
-declare const FLAG_KEYS: readonly ["optableDebug", "optableDisableConsent", "optableResolve1P", "optableResolve3P", "optableEnableAnalytics", "optableControlGroup", "optableForceTargeting", "optableForceGlobalRouting", "optableForceSkipMerge"];
+declare const FLAG_KEYS: readonly ["optableDebug", "optableDisableConsent", "optableResolve1P", "optableResolve3P", "optableEnableAnalytics", "optableControlGroup", "optableForceTargeting", "optableForceGlobalRouting", "optableForceSkipMerge", "optableForceTokenize", "optableResolveId5", "optableResolveID5ID"];
 export type FlagKey = (typeof FLAG_KEYS)[number];
 export type Flags = Partial<Record<FlagKey, string>>;
+export declare function persistFlagsFromURL(keys: readonly string[]): Record<string, string>;
 export declare function getFlags(): Flags;
 export declare function resetFlags(): void;
+export declare function flagEnabled(key: FlagKey): boolean;
 export {};

package/lib/dist/core/flags.js

@@ -8,20 +8,38 @@ const FLAG_KEYS = [
     "optableForceTargeting",
     "optableForceGlobalRouting",
     "optableForceSkipMerge",
+    "optableForceTokenize",
+    "optableResolveId5",
+    "optableResolveID5ID",
 ];
-function parseFlags() {
-    const flags = {};
+// Reads the given keys from the URL query string (a bare key means "1") and
+// persists them to sessionStorage for the rest of the tab session. Exported
+// for wrapper bundles with keys of their own outside FLAG_KEYS.
+export function persistFlagsFromURL(keys) {
+    const found = {};
     try {
         const params = new URLSearchParams(window.location.search);
-        for (const key of FLAG_KEYS) {
+        for (const key of keys) {
             if (params.has(key)) {
-                flags[key] = params.get(key) || "1";
+                found[key] = params.get(key) || "1";
             }
         }
     }
     catch (_a) {
         // URL params unavailable
     }
+    try {
+        for (const key of Object.keys(found)) {
+            sessionStorage.setItem(key, found[key]);
+        }
+    }
+    catch (_b) {
+        // sessionStorage unavailable
+    }
+    return found;
+}
+function parseFlags() {
+    const flags = persistFlagsFromURL(FLAG_KEYS);
     try {
         for (const key of FLAG_KEYS) {
             if (!(key in flags)) {
@@ -32,7 +50,7 @@ function parseFlags() {
             }
         }
     }
-    catch (_b) {
+    catch (_a) {
         // sessionStorage unavailable
     }
     return flags;
@@ -47,3 +65,21 @@ export function getFlags() {
 export function resetFlags() {
     _flags = null;
 }
+/*
+ * True when a flag carries a value and is not explicitly disabled.
+ *
+ * Flags carry string values ("?optableDebug" and "?optableDebug=1" both yield
+ * "1"), so a bare truthiness test treats the string "0" as enabled. Callers
+ * that only care whether a flag is on should use this rather than testing the
+ * raw value, so "?optableDebug=0" turns the flag off as a reader would expect.
+ *
+ * An empty value counts as disabled. A URL cannot produce one, but sessionStorage
+ * written by other code can.
+ *
+ * Flags with more than two states — optableControlGroup, where "1" and "0"
+ * select different variants — should read getFlags() and compare explicitly.
+ */
+export function flagEnabled(key) {
+    const value = getFlags()[key];
+    return !!value && value !== "0";
+}

package/lib/dist/core/log.d.ts

@@ -0,0 +1,4 @@
+declare function consoleLog(prefix: string, level: string, message: string, ...args: any[]): void;
+declare function debugLog(level: string, message: string, ...args: any[]): void;
+declare function optableMessage(...args: any[]): void;
+export { consoleLog, debugLog, optableMessage };

package/lib/dist/core/log.js

@@ -0,0 +1,20 @@
+import { flagEnabled } from "./flags";
+// Level-aware console writer. Ungated — for callers with their own enablement
+// logic, like the RTD module's enableLogging option.
+function consoleLog(prefix, level, message, ...args) {
+    const logMethod = ["error", "warn", "info"].includes(level) ? level : "log";
+    console[logMethod](`${prefix} ${message}`, ...args); // eslint-disable-line no-console
+}
+// Debug logger gated on the optableDebug flag (URL param or sessionStorage).
+function debugLog(level, message, ...args) {
+    if (flagEnabled("optableDebug")) {
+        consoleLog("Optable:", level, message, ...args);
+    }
+}
+// Debug logger for wrapper bundles, gated on the optableDebug flag.
+function optableMessage(...args) {
+    if (flagEnabled("optableDebug")) {
+        console.log("[OPTABLE WRAPPER]", ...args); // eslint-disable-line no-console
+    }
+}
+export { consoleLog, debugLog, optableMessage };

package/lib/dist/core/network.js

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 import { default as buildInfo } from "../build.json";
 import { LocalStorage } from "./storage";
 import { deviceSignals } from "./signals";
+import { oisHeaderName, oisRequestID, readOISHeader } from "./ois";
 function buildRequest(path, config, init) {
     const { host, cookies, insecure } = config;
     const url = new URL(path, `${insecure ? "http" : "https"}://${host}`);
@@ -59,16 +60,33 @@ function buildRequest(path, config, init) {
     }
     const requestInit = Object.assign({}, init);
     requestInit.credentials = config.consent.deviceAccess ? "include" : "omit";
+    const headers = new Headers(requestInit.headers);
+    requestInit.headers = headers;
     if (config.mockedIP) {
-        requestInit.headers = new Headers(requestInit.headers);
-        requestInit.headers.set("X-Forwarded-For", config.mockedIP);
+        headers.set("X-Forwarded-For", config.mockedIP);
+    }
+    if (config.ois) {
+        const oisID = oisRequestID(config, url.pathname);
+        if (oisID) {
+            try {
+                headers.set(oisHeaderName, oisID);
+            }
+            catch (_a) {
+                // A stored value carrying characters a header cannot hold must not brick every call.
+            }
+        }
     }
     const request = new Request(url.toString(), requestInit);
     return request;
 }
 function fetch(path, config, init) {
     return __awaiter(this, void 0, void 0, function* () {
-        const response = yield globalThis.fetch(buildRequest(path, config, init));
+        const request = buildRequest(path, config, init);
+        const response = yield globalThis.fetch(request);
+        // Ahead of the error throw below: a non-2xx can still carry a derived id.
+        if (config.ois) {
+            readOISHeader(config, new URL(request.url).pathname, response.headers);
+        }
         const contentType = response.headers.get("Content-Type");
         const data = (contentType === null || contentType === void 0 ? void 0 : contentType.startsWith("application/json")) ? yield response.json() : yield response.text();
         if (!response.ok) {

package/lib/dist/core/ois.d.ts

@@ -0,0 +1,13 @@
+import type { ResolvedConfig } from "../config";
+declare const oisHeaderName = "X-Optable-OID";
+type OISState = {
+    id: string | null;
+    storageKey: string;
+};
+declare function getOISID(config: ResolvedConfig): string | null;
+declare function readOISHeader(config: ResolvedConfig, pathname: string, headers: Headers): void;
+declare function oisRequestID(config: ResolvedConfig, pathname: string): string | null;
+declare function clearOISID(config: ResolvedConfig): void;
+declare function getOISState(config: ResolvedConfig): OISState;
+export { oisHeaderName, readOISHeader, oisRequestID, getOISID, getOISState, clearOISID };
+export type { OISState };

package/lib/dist/core/ois.js

@@ -0,0 +1,55 @@
+import { LocalStorage } from "./storage";
+const oisHeaderName = "X-Optable-OID";
+const oisChangeEventName = "optable-ois:change";
+const HEADER_PATHS = new Set(["/identify", "/uid2/token", "/profile"]);
+function derivesOISID(pathname) {
+    return HEADER_PATHS.has(pathname);
+}
+function getOISID(config) {
+    return new LocalStorage(config).getOIS();
+}
+function readOISHeader(config, pathname, headers) {
+    if (!derivesOISID(pathname) || !config.consent.deviceAccess) {
+        return;
+    }
+    const id = headers.get(oisHeaderName);
+    if (!id) {
+        return;
+    }
+    const storage = new LocalStorage(config);
+    if (storage.getOIS() === id) {
+        return;
+    }
+    try {
+        storage.setOIS(id);
+    }
+    catch (_a) {
+        // Storage full or blocked.
+        return;
+    }
+    notifyChange(config, { id, storageKey: storage.oisKey() });
+}
+function oisRequestID(config, pathname) {
+    if (!derivesOISID(pathname) || !config.consent.deviceAccess) {
+        return null;
+    }
+    return getOISID(config);
+}
+function clearOISID(config) {
+    const storage = new LocalStorage(config);
+    if (storage.getOIS() === null) {
+        return;
+    }
+    storage.clearOIS();
+    notifyChange(config, { id: null, storageKey: storage.oisKey() });
+}
+function getOISState(config) {
+    const storage = new LocalStorage(config);
+    return { id: storage.getOIS(), storageKey: storage.oisKey() };
+}
+function notifyChange(config, state) {
+    window.dispatchEvent(new CustomEvent(oisChangeEventName, {
+        detail: Object.assign({ instance: config.node || config.host }, state),
+    }));
+}
+export { oisHeaderName, readOISHeader, oisRequestID, getOISID, getOISState, clearOISID };

package/lib/dist/core/prebid/rtd.js

@@ -19,7 +19,8 @@ var __rest = (this && this.__rest) || function (s, e) {
     return t;
 };
 // RTD (Real-Time Data) module for Prebid.js integration
-import { getFlags } from "../flags";
+import { flagEnabled } from "../flags";
+import { consoleLog } from "../log";
 // Merge strategies for EIDs
 function appendMergeStrategy(existingEids, newEids) {
     return [...existingEids, ...newEids];
@@ -77,12 +78,6 @@ function forceGlobalRouting() {
         source.routes = ["global"];
     });
 }
-// Simple logging utility
-function log(level, message, ...args) {
-    const prefix = "Optable RTD:";
-    const logMethod = ["error", "warn", "info"].includes(level) ? level : "log";
-    console[logMethod](`${prefix} ${message}`, ...args); // eslint-disable-line no-console
-}
 // Helper function to get targeting data from cache
 function targetingFromCache(config = {}) {
     var _a;
@@ -269,19 +264,18 @@ function liveIntentUID2(ortb2) {
 }
 function buildRTD(options = {}) {
     var _a, _b, _c, _d, _e, _f, _g;
-    const flags = getFlags();
-    if (flags.optableForceGlobalRouting || options.forceGlobalRouting) {
+    if (flagEnabled("optableForceGlobalRouting") || options.forceGlobalRouting) {
         forceGlobalRouting();
     }
     return {
-        enableLogging: !!flags.optableDebug || ((_a = options.enableLogging) !== null && _a !== void 0 ? _a : false),
+        enableLogging: flagEnabled("optableDebug") || ((_a = options.enableLogging) !== null && _a !== void 0 ? _a : false),
         log(level, message, ...args) {
             if (this.enableLogging) {
-                log(level, message, ...args);
+                consoleLog("Optable RTD:", level, message, ...args);
             }
         },
         eidSources: (_b = options.eidSources) !== null && _b !== void 0 ? _b : Object.assign({}, defaultEIDSources),
-        skipMerge: flags.optableForceSkipMerge
+        skipMerge: flagEnabled("optableForceSkipMerge")
             ? () => true
             : options.skipMerge !== undefined
                 ? options.skipMerge

package/lib/dist/core/regs/consent.js

@@ -1,4 +1,5 @@
 import { inferRegulation } from "./regulations";
+import { flagEnabled } from "../flags";
 import * as gpp from "./gpp";
 import * as tcf from "./tcf";
 function applicableReg(defaultReg, cmp) {
@@ -102,6 +103,16 @@ function computeConsent(defaultReg, cmp, conf = {}) {
     return consent;
 }
 function getConsent(defaultReg, conf = {}) {
+    // QA bypass: grant all permissions and skip the CMP entirely.
+    if (flagEnabled("optableDisableConsent")) {
+        return {
+            reg: null,
+            deviceAccess: true,
+            createProfilesForAdvertising: true,
+            useProfilesForAdvertising: true,
+            measureAdvertisingPerformance: true,
+        };
+    }
     const cmp = {};
     tcf.cmpapi.installFrameProxy();
     gpp.cmpapi.installFrameProxy();

package/lib/dist/core/storage-keys.d.ts

@@ -7,6 +7,7 @@ export declare function encodeBase64(str: string): string;
 declare function generateSiteKeys(config: ResolvedConfig): StorageKeys;
 declare function generateTargetingKeys(config: ResolvedConfig): StorageKeys;
 declare function generatedPairKeys(): StorageKeys;
+declare function generateOISKeys(config: ResolvedConfig): StorageKeys;
 declare function generatePassportKeys(config: ResolvedConfig): StorageKeys;
 export type { StorageKeys };
-export { generateSiteKeys, generatedPairKeys, generatePassportKeys, generateTargetingKeys };
+export { generateSiteKeys, generatedPairKeys, generatePassportKeys, generateTargetingKeys, generateOISKeys };

package/lib/dist/core/storage-keys.js

@@ -28,6 +28,12 @@ function generateTargetingKeys(config) {
 function generatedPairKeys() {
     return { write: [pairStorageKey], read: [pairStorageKey] };
 }
+// Generate the keys for the OIS id storage
+// The keys are generated based on the host and node configs
+function generateOISKeys(config) {
+    const key = `OPTABLE_OIS_${getWriteKeyBase64FromConfig(config)}`;
+    return { write: [key], read: [key] };
+}
 // Generate the keys for the passport storage
 // The keys are generated based on the host and node configs
 // We need to keep backward compatibility with the legacy host cache
@@ -50,4 +56,4 @@ function generatePassportKeys(config) {
     }
     return { write, read };
 }
-export { generateSiteKeys, generatedPairKeys, generatePassportKeys, generateTargetingKeys };
+export { generateSiteKeys, generatedPairKeys, generatePassportKeys, generateTargetingKeys, generateOISKeys };

package/lib/dist/core/storage.d.ts

@@ -8,13 +8,19 @@ declare class LocalStorage {
     private targetingKeys;
     private siteKeys;
     private pairKeys;
+    private oisKeys;
     private storage;
     constructor(config: ResolvedConfig);
     getPassport(): string | null;
     setPassport(passport: string): void;
     getVisitorId(): string | null;
+    getOIS(): string | null;
+    setOIS(id: string): void;
+    clearOIS(): void;
+    oisKey(): string;
     getTargeting(): TargetingResponse | null;
     setTargeting(targeting?: TargetingResponse | null): void;
+    updateTargeting(update: (targeting: TargetingResponse) => boolean): TargetingResponse | null;
     getSite(): SiteResponse | null;
     setSite(site?: SiteResponse | null): void;
     setPairIDs(targeting: TargetingResponse): void;

package/lib/dist/core/storage.js

@@ -1,5 +1,5 @@
 import { LocalStorageProxy } from "./regs/storage";
-import { generatedPairKeys, generatePassportKeys, generateSiteKeys, generateTargetingKeys, } from "./storage-keys";
+import { generatedPairKeys, generateOISKeys, generatePassportKeys, generateSiteKeys, generateTargetingKeys, } from "./storage-keys";
 const pairEIDSource = "pair-protocol.com";
 class LocalStorage {
     constructor(config) {
@@ -8,6 +8,7 @@ class LocalStorage {
         this.targetingKeys = generateTargetingKeys(config);
         this.siteKeys = generateSiteKeys(config);
         this.pairKeys = generatedPairKeys();
+        this.oisKeys = generateOISKeys(config);
         this.storage = new LocalStorageProxy(this.config.consent);
     }
     getPassport() {
@@ -36,6 +37,18 @@ class LocalStorage {
             return null;
         }
     }
+    getOIS() {
+        return this.readStorageKeys(this.oisKeys);
+    }
+    setOIS(id) {
+        this.writeToStorageKeys(this.oisKeys, id);
+    }
+    clearOIS() {
+        this.clearStorageKeys(this.oisKeys);
+    }
+    oisKey() {
+        return this.oisKeys.write[0];
+    }
     getTargeting() {
         const raw = this.readStorageKeys(this.targetingKeys);
         return raw ? JSON.parse(raw) : null;
@@ -47,6 +60,32 @@ class LocalStorage {
         this.writeToStorageKeys(this.targetingKeys, JSON.stringify(targeting));
         this.setPairIDs(targeting);
     }
+    // Updates every stored copy of the targeting response independently: the
+    // private and public copies can hold different representations, so each is
+    // read, updated and written back on its own. Returns the last updated copy.
+    updateTargeting(update) {
+        let updated = null;
+        const keys = [...new Set([...this.targetingKeys.read, ...this.targetingKeys.write])].filter(Boolean);
+        for (const key of keys) {
+            const raw = this.storage.getItem(key);
+            if (!raw) {
+                continue;
+            }
+            let targeting;
+            try {
+                targeting = JSON.parse(raw);
+            }
+            catch (_a) {
+                // Leave an unparseable copy untouched.
+                continue;
+            }
+            if (update(targeting)) {
+                this.storage.setItem(key, JSON.stringify(targeting));
+                updated = targeting;
+            }
+        }
+        return updated;
+    }
     getSite() {
         const raw = this.readStorageKeys(this.siteKeys);
         return raw ? JSON.parse(raw) : null;

package/lib/dist/sdk.d.ts

@@ -7,6 +7,7 @@ import { SiteResponse } from "./edge/site";
 import { TargetingKeyValues, TargetingResponse, TargetingRequest, PrebidORTB2 } from "./edge/targeting";
 import { ContextualSegmentsResponse, ContextualTargetingKeyValues, ContextualTargetingKeyValuesOptions } from "./edge/contextual_segments";
 import { TokenizeResponse } from "./edge/tokenize";
+import type { OISState } from "./core/ois";
 declare class OptableSDK {
     static version: string;
     dcn: ResolvedConfig;
@@ -14,8 +15,7 @@ declare class OptableSDK {
     private contextSent;
     private contextConfig;
     private contextualResponse;
-    private passportNullWarned;
-    private visitorIdNullWarned;
+    private warned;
     constructor(dcn: InitConfig);
     initialize(): Promise<void>;
     identify(...ids: string[]): Promise<void>;
@@ -24,8 +24,12 @@ declare class OptableSDK {
     targetingFromCache(): TargetingResponse | null;
     site(): Promise<SiteResponse>;
     siteFromCache(): SiteResponse | null;
+    private warnOnce;
     passport(): string | null;
     visitorId(): string | null;
+    oisId(): string | null;
+    oisState(): OISState;
+    oisClear(): void;
     targetingClearCache(): void;
     prebidORTB2(): Promise<PrebidORTB2>;
     prebidORTB2FromCache(): PrebidORTB2;

package/lib/dist/sdk.js

@@ -22,13 +22,14 @@ import { ContextualSegments, ContextualTargetingKeyValues, } from "./edge/contex
 import { sha256 } from "js-sha256";
 import { Tokenize } from "./edge/tokenize";
 import { LocalStorage } from "./core/storage";
+import { clearOISID, getOISID, getOISState } from "./core/ois";
+import { consoleLog } from "./core/log";
 class OptableSDK {
     constructor(dcn) {
         this.contextSent = false;
         this.contextConfig = null;
         this.contextualResponse = null;
-        this.passportNullWarned = false;
-        this.visitorIdNullWarned = false;
+        this.warned = new Set();
         this.dcn = getConfig(dcn);
         this.contextConfig = normalizeContextConfig(dcn.pageContext);
         if (this.dcn.initContextual && !this.contextConfig) {
@@ -83,11 +84,17 @@ class OptableSDK {
     siteFromCache() {
         return SiteFromCache(this.dcn);
     }
+    warnOnce(key, message) {
+        if (this.warned.has(key)) {
+            return;
+        }
+        this.warned.add(key);
+        consoleLog("[Optable]", "warn", message);
+    }
     passport() {
         const value = new LocalStorage(this.dcn).getPassport();
-        if (value === null && !this.passportNullWarned) {
-            this.passportNullWarned = true;
-            console.warn("[Optable] passport() returned null. The passport is cached in localStorage once the DCN returns one. " +
+        if (value === null) {
+            this.warnOnce("passport", "passport() returned null. The passport is cached in localStorage once the DCN returns one. " +
                 "Call before initialization (await sdk.site() or sdk.targeting()) may return null, and deployments where the DCN " +
                 "does not echo the passport in response bodies will never populate it client-side.");
         }
@@ -95,14 +102,28 @@ class OptableSDK {
     }
     visitorId() {
         const value = new LocalStorage(this.dcn).getVisitorId();
-        if (value === null && !this.visitorIdNullWarned) {
-            this.visitorIdNullWarned = true;
-            console.warn("[Optable] visitorId() returned null. The visitor ID is derived from the passport JWT in localStorage. " +
+        if (value === null) {
+            this.warnOnce("visitorId", "visitorId() returned null. The visitor ID is derived from the passport JWT in localStorage. " +
                 "Call before initialization (await sdk.site() or sdk.targeting()) may return null, and deployments where the DCN " +
                 "does not echo the passport in response bodies will never populate it client-side.");
         }
         return value;
     }
+    oisId() {
+        const value = getOISID(this.dcn);
+        if (value === null && this.dcn.ois) {
+            this.warnOnce("oisId", "oisId() returned null. The derived OIS id is cached once the DCN returns it on the X-Optable-OID " +
+                "response header, which happens on the first identify() or profile() call — not during " +
+                "initialization. A node with OIS ID derivation disabled, or a non-residential IP, never returns one.");
+        }
+        return value;
+    }
+    oisState() {
+        return getOISState(this.dcn);
+    }
+    oisClear() {
+        clearOISID(this.dcn);
+    }
     targetingClearCache() {
         TargetingClearCache(this.dcn);
     }