@dolby-optiview/ads-sdk-core 1.0.0-beta.1

package/dist/vendor/lens-sdk/types.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Join once per integrator instance, at boot: who I am (namespace) and where
+ * my events go (destinations). Viewing sessions then start and end through
+ * the handle — there is no re-join between sessions.
+ */
+export interface LensJoinOptions {
+    /**
+     * The integrator's product identity ('ads', 'live', …), NOT a session
+     * concept: the same namespace spans every session of this handle. Bound at
+     * join so no product can emit as another; destination filters key on it.
+     */
+    namespace: string;
+    destinations?: LensDestination[];
+    /** Optional — 'granted' by default; integrators that don't need a consent gate can ignore it. */
+    consent?: LensConsent;
+    /**
+     * Emit-path violations (bad custom key or event names) throw when true —
+     * for development and CI builds. Default false: the offending key or event
+     * is dropped with a console warning, and playback is never at risk. Setup
+     * problems (join/startSession arguments) always throw.
+     */
+    strict?: boolean;
+    /**
+     * Cadence of the session's liveness report (CMCD `e=t`), which Lens sends
+     * on its own — integrators never report it. Spec default 30000 ms; 0 turns
+     * it off; otherwise at least 1000 ms.
+     */
+    heartbeatMs?: number;
+}
+export type LensBackend = 'production' | 'disabled';
+export interface LensConfigureOptions {
+    backend: LensBackend;
+    /**
+     * Automatic flushing at the platform's lifecycle cliff (`pagehide` here),
+     * on by default. Turn off only when the host flushes from its own
+     * lifecycle via {@link LensHandle.flush}. Each `configure` applies it
+     * anew; omitting it restores the default.
+     */
+    lifecycleFlush?: boolean;
+}
+export interface LensHandle {
+    /**
+     * Temporary session-control door: the integrator tells Lens when a viewing
+     * session starts/ends. Starting while one is active rolls it (new sid).
+     * The player-adapter phase will absorb this into automatic session management.
+     */
+    startSession(options?: LensStartSessionOptions): LensSession;
+    endSession(): void;
+    /** The active session, or null between sessions. */
+    readonly session: LensSession | null;
+    /**
+     * Report a standard CMCD event. The payload type follows the token:
+     * free-form events take {@link LensPayload}; spec-shaped events get
+     * compile-checked typed payloads. Dropped when no session is active or
+     * consent is denied; registered CMCD names inside `custom` throw.
+     */
+    emit<P extends LensPayload>(type: LensEventType<P>, payload?: P): void;
+    /**
+     * Report a custom event — anything the spec has no type for. Lowered to the
+     * CMCD custom event (`ce`) with `name` as the custom event name (`cen`) on
+     * the wire, unqualified per spec and in-core precedent. `name` must be a
+     * simple token (letters, digits, '-', '_'); otherwise the event is dropped.
+     * Takes the same {@link LensPayload} shape as free-form standard events.
+     */
+    emitCustom(name: string, payload?: LensPayload): void;
+    /**
+     * Attach this integrator's current state to the session's liveness reports:
+     * every heartbeat from now on carries these keys, in this handle's namespace
+     * either way — keys come and go, the namespace does not. Latest call wins; no
+     * argument (or nothing valid left) goes back to a plain liveness report. Sets
+     * state only — it never sends and never shifts the cadence. The payload's
+     * top level is Lens's; `custom` is yours.
+     */
+    setHeartbeatPayload(payload?: LensPayload): void;
+    /**
+     * Change the liveness cadence on a live handle — faster during an ad break,
+     * slower in the background. Same rule as `heartbeatMs` at join: `0` is off,
+     * anything else is a whole number of milliseconds of at least 1000. A new
+     * cadence opens with a report and runs from there, the way a session's does;
+     * `0` stops without one, and re-setting the interval already in force does
+     * nothing.
+     */
+    setHeartbeatInterval(ms: number): void;
+    setConsent(consent: LensConsent): void;
+    /**
+     * Send everything pending now. Not needed by a standard integrator —
+     * lifecycle flushing already covers the common cliffs; this is for hosts
+     * that opted out of it or live outside the observed lifecycles. Does not
+     * end the session; no-op after dispose.
+     */
+    flush(): void;
+    dispose(): void;
+}
+/**
+ * The one payload shape: custom keys always live under `custom`, so a future
+ * spec revision adding typed fields to any event is additive — never a
+ * call-site break. Typed events extend this with their spec fields at the
+ * top level.
+ */
+export interface LensPayload {
+    /** Custom keys — short names; registered CMCD names throw at emit. */
+    custom?: LensEventKeys;
+}
+declare const payloadType: unique symbol;
+/**
+ * A standard CMCD (CTA-5004-B) event type token, carrying the payload type
+ * it accepts — grows additively as more of the spec is adopted. v0 ships the
+ * ad set ({@link LensPayload}, with {@link LensAdPayload} on the ad-identity
+ * events); anything not listed here goes
+ * through `emitCustom`. Wire codes are the spec values.
+ */
+export interface LensEventType<P extends LensPayload = LensPayload> {
+    readonly wireCode: string;
+    /** Phantom marker anchoring the payload type invariantly — never set at runtime. */
+    readonly [payloadType]?: (payload: P) => P;
+}
+/**
+ * Payload for the ad events that carry content identity (CTA-5004-B §8.2.8):
+ * `AD_START` swaps the session's `cid` for the ad's until the ad or its break
+ * ends; `AD_END`/`AD_SKIP` may carry it to label themselves when arriving out
+ * of order — they never re-open a swap. Content-replacing break formats only:
+ * overlays are not an ad for `cid` purposes and must not feed this field.
+ */
+export interface LensAdPayload extends LensPayload {
+    /** The ad's own content ID (1-128 printable ASCII), reported as `cid`. */
+    contentId?: string;
+}
+export declare const LensEventType: {
+    /** An ad break has started (wire: 'abs'). */
+    readonly AD_BREAK_START: LensEventType<LensPayload>;
+    /** An ad has started playing (wire: 'as'). */
+    readonly AD_START: LensEventType<LensAdPayload>;
+    /** An ad has ended (wire: 'ae'). */
+    readonly AD_END: LensEventType<LensAdPayload>;
+    /** An ad break has ended (wire: 'abe'). */
+    readonly AD_BREAK_END: LensEventType<LensPayload>;
+    /** An ad was skipped (wire: 'sk'). */
+    readonly AD_SKIP: LensEventType<LensAdPayload>;
+};
+/**
+ * Marks a custom value that must be emitted as an unquoted structured-field
+ * token. The marker avoids inferring token-ness from ordinary enum strings.
+ */
+export declare class LensToken {
+    readonly value: string;
+    constructor(value: string);
+}
+/**
+ * Event payload custom keys — CMCD value types plus LensToken, so every key
+ * serializes cleanly. Short names everywhere the integrator and the backend
+ * look; the CMCD wire hop alone qualifies them with the reverse-DNS prefix (a
+ * transport artifact, stripped again on ingest). Registered CMCD key names
+ * throw at emit; invalid token values are dropped.
+ */
+export type LensEventKeys = Record<string, string | number | boolean | LensToken>;
+export interface LensStartSessionOptions {
+    /** Externally steered session id (e.g. injected by discovery); Lens generates a UUID when absent. */
+    sessionId?: string;
+    /** The main content's ID (1-128 printable ASCII), stamped as `cid` on every report of the session. */
+    contentId?: string;
+    /** Streaming format (`sf`): 'd' DASH, 'h' HLS, 's' Smooth, 'e' HESP, 'o' other. */
+    streamingFormat?: 'd' | 'h' | 's' | 'e' | 'o';
+    /** Stream type (`st`): 'v' VOD, 'l' live, 'll' low-latency live. */
+    streamType?: 'v' | 'l' | 'll';
+}
+export interface LensDestination {
+    url: string;
+    filter?: LensDestinationFilter;
+    /**
+     * Wire format for this destination: 'cmcd' (default) — CMCD key
+     * serialization posted as application/cmcd, for CMCD-aware receivers like
+     * the OptiView ingest; 'json' — short-keyed reports posted as
+     * application/json, for endpoints that don't parse CMCD (customer ad-ops
+     * hooks).
+     */
+    format?: 'cmcd' | 'json';
+    /**
+     * Whether this destination receives liveness reports (`e=t`).
+     * Defaults to true for 'cmcd' — a CMCD event target is what the heartbeat
+     * is specified for — and false for every other format, so receivers only
+     * get liveness traffic they asked for.
+     */
+    heartbeat?: boolean;
+    /** Delivery hints, consumed by the transport: flush at maxEvents pending, or when the oldest event has waited maxDelayMs (0 = per event). */
+    batch?: {
+        maxEvents?: number;
+        maxDelayMs?: number;
+    };
+}
+export interface LensDestinationFilter {
+    namespaces?: string[];
+    /** Matches the event's wire type — or the custom name for custom events. */
+    events?: string[];
+}
+export type LensConsent = 'granted' | 'denied';
+export interface LensSession {
+    readonly sessionId: string;
+}
+/** Wire-side only — what destinations receive. Integrators never construct it. */
+export interface LensEvent {
+    /** The spec wire code ('abs', 'as', …) — or 'ce' for custom events. */
+    type: string;
+    /** The custom event name (spec `cen`); present only when type is 'ce'. */
+    customName?: string;
+    namespace: string;
+    /** The event's custom keys (the payload's `custom` map). */
+    keys?: LensEventKeys;
+    /** Epoch milliseconds. */
+    timestamp: number;
+    session: LensSession;
+    /** The effective content ID (`cid`) at emit time — the ad's during a swap, the session's otherwise. */
+    contentId?: string;
+    /** Streaming format (`sf`), from the session. */
+    streamingFormat?: string;
+    /** Stream type (`st`), from the session. */
+    streamType?: string;
+}
+export {};

package/dist/vendor/lens-sdk/user-id.d.ts

@@ -0,0 +1,5 @@
+export declare function currentUserId(): string;
+/** Consent revoked: the ID is identifying, so it is deleted — a later grant starts fresh. */
+export declare function clearUserId(): void;
+export declare function setUserIdForTesting(next: string | undefined): void;
+export declare function resetUserIdForTesting(): void;

package/dist/vendor/lens-sdk/validation.d.ts

@@ -0,0 +1,30 @@
+import { type LensEventKeys } from './types';
+/** Keys Lens stamps itself — the environment plus the user ID (docs/internals.md). */
+export declare const LENS_RESERVED: Set<string>;
+/**
+ * Name problems are contract violations: strict mode throws; by default the
+ * offending key is dropped with a warning. Ordinary values pass through
+ * untouched; explicit token values are grammar-checked.
+ */
+export declare function checkedCustomKeys(custom: LensEventKeys | undefined, strict: boolean): LensEventKeys | undefined;
+/** True when the event may be sent; reports the violation otherwise. */
+export declare function checkedCustomEventName(name: string, strict: boolean): boolean;
+/** Session-start content IDs fail loudly — setup arguments, like requireSetupString. */
+export declare function requireContentId(value: string): void;
+export declare function requireStreamingFormat(value: string): void;
+export declare function requireStreamType(value: string): void;
+/**
+ * Ad content IDs arrive on the emit path: strict throws, default warns and
+ * drops the field — the event itself still goes out.
+ */
+export declare function checkedContentId(value: string | undefined, strict: boolean): string | undefined;
+/** Setup strings fail loudly regardless of mode — they run once, at boot. */
+export declare function requireSetupString(value: string, what: string): void;
+/** Reserved for reports the SDK would send on its own behalf — no integrator may claim it. */
+export declare const LENS_NAMESPACE = "lens";
+export declare function requireNamespace(value: string): void;
+/** The spec's default interval-report cadence (CTA-5004-B Table 1). */
+export declare const DEFAULT_HEARTBEAT_MS = 30000;
+/** Below this a heartbeat is a flood, not a liveness signal. */
+export declare const MIN_HEARTBEAT_MS = 1000;
+export declare function requireHeartbeatMs(value: number): void;

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@dolby-optiview/ads-sdk-core",
+  "version": "1.0.0-beta.1",
+  "description": "OptiView Ads SDK Core - Player-agnostic ad insertion",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./diagnostics": {
+      "types": "./dist/diagnostics/index.d.ts",
+      "default": "./dist/diagnostics/index.js"
+    },
+    "./id3": {
+      "types": "./dist/id3/index.d.ts",
+      "default": "./dist/id3/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal/index.d.ts",
+      "default": "./dist/internal/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json && node ../../scripts/vendor-lens-web.mjs",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "dolby",
+    "ads",
+    "sgai",
+    "video",
+    "advertising"
+  ],
+  "author": "Dolby",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "homepage": "https://ads-sdk.xnappet.live",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": [
+    "dist/vendor/**/*.js"
+  ]
+}