@uniformdev/context 20.7.1-alpha.12 → 20.7.1-alpha.121

package/dist/{types-EJl31yuP.d.mts → types-HcKr1VVF.d.mts}

@@ -76,6 +76,17 @@ type VisitorData = {
     personalizeVariants?: PersonalizeVariants;
 };
 declare const emptyVisitorData: () => VisitorData;
+/**
+ * Canvas-specific data that should be managed separately from regular context updates
+ */
+type CompositionMetadata = {
+    /** The composition ID always required, otherwise whole metadata should not be set */
+    compositionId: string;
+    /** The matched route from router endpoint. Same as matched project map node pathname */
+    matchedRoute?: string;
+    /** Dynamic inputs for the route */
+    dynamicInputs?: Record<string, string>;
+};
 /**
  * Expresses a 'patch' to the Uniform Context state
  */
@@ -85,6 +96,11 @@ type ContextState = {
     quirks: Quirks;
     enrichments: EnrichmentData[];
     events: EventData[];
+    /**
+     * Metadata about the composition that is being rendered right now.
+     * if you have multiple compositions on the page, please set this one manually.
+     */
+    compositionMetadata?: CompositionMetadata;
 };
 type ContextStateUpdate = {
     /** The new effective state of the visitor after this state update is applied */
@@ -179,6 +195,10 @@ type ServerToClientTransitionState = Pick<Partial<VisitorData>, 'quirks' | 'test
      * Storage commands that the server
      */
     commands?: StorageCommands[];
+    /**
+     * Composition metadata from the server side
+     */
+    compositionMetadata?: CompositionMetadata;
 };
 declare const SERVER_STATE_ID = "__UNIFORM_DATA__";
 type TransitionDataStoreEvents = {
@@ -374,6 +394,7 @@ declare class ManifestInstance {
      */
     computeAggregateDimensions(primitiveScores: ScoreVector): ScoreVector;
     getDimensionByKey(scoreKey: string): EnrichmentCategory | Signal | undefined;
+    getAggregateDimensionByKey(scoreKey: string): AggregateDimension | undefined;
 }
 
 interface paths {
@@ -859,6 +880,10 @@ type LogMessages = {
     }>;
     /** Final result for a personalized variation */
     303: MessageFunc<boolean>;
+    /** Personalization algorithm not found */
+    304: MessageFunc<{
+        algorithm: string;
+    }>;
     /** A/B test placement executing */
     400: MessageFunc<string>;
     /** A/B Test definition did not exist */
@@ -898,23 +923,34 @@ type LogMessageSingle<TID extends keyof LogMessages = keyof LogMessages> = [
 type LogMessageGroup<TID extends keyof LogMessages = keyof LogMessages> = [severity: Severity, id: TID, group: 'GROUP', ...args: Parameters<LogMessages[TID]>] | [severity: Severity, id: TID, group: 'ENDGROUP'];
 type LogDrain = (message: LogMessage) => void;
 
-type VariantMatchCriteria = {
+/** Data for a personalization variation using the top-down criteria selection algorithm */
+interface VariantMatchCriteria extends VariationMatchMetadata {
     /**
      * Operation for match criteria
      *
      * @defaultValue `&`
      */
     op?: '&' | '|';
-    crit: DimensionMatch[];
-    /**
-     * Name of the variant for analytics tracking.
-     */
-    name?: string;
+    crit: Array<DimensionMatch | QuirkMatch>;
     /**
      * Control group percentage for the variant.
      */
     control?: number;
-};
+}
+/** Data for a personalization variation using the TODO selection algorithm */
+interface VariationMatchDimensionCriteria extends VariationMatchMetadata {
+    /** The dimension this content is relevant to */
+    dim: string | undefined;
+}
+/** Data that must exist on a personalization variation regardless of selection algorithm */
+interface VariationMatchMetadata {
+    /**
+     * Name of the variation for analytics tracking.
+     * NOTE: name is optional for backwards compatibility, but it is HIGHLY recommended to specify a name
+     * as the default fallback is not helpfully named and is reliant on the order of the variations array.
+     */
+    name?: string;
+}
 type DimensionMatch = {
     /**
      * Left hand side of the match expression (name of dimension in score vector)
@@ -953,17 +989,48 @@ type DimensionMatch = {
      */
     rDim?: string;
 };
+type QuirkMatch = {
+    /**
+     * Type of match expression; 'q' discriminates quirk matches from dimension matches
+     */
+    t: 'q';
+    /**
+     * Left hand side of the match expression (name of quirk)
+     * NOTE: if the quirk is not present
+     */
+    l: string;
+    /**
+     * Operator of the match expression
+     * Comparison operators:
+     * =: `l` is equal to the right hand side expression
+     * !=: `l` is not equal to the right hand side expression
+     */
+    op: '=' | '!=';
+    /**
+     * Right hand side of the match expression
+     * This value is treated as a constant value, if it is present. If it's a string, it is parsed to an integer.
+     * To reference another score dimension as the RHS, use the `rDim` property instead.
+     * `r` and `rDim` are mutually exclusive; if both are specified, then `rDim` wins.
+     */
+    r: string;
+    /**
+     * Only here to maintain object compatibility with DimensionMatch.
+     * Completely ignored.
+     * @deprecated this is not used with QuirkMatch.
+     */
+    rDim?: string;
+};
 
 /** Content that is tagged for adding enrichment score when triggered by behavior (i.e. being shown that content) */
 type BehaviorTag = {
     beh?: EnrichmentData[];
 };
 /** Defines the shape of a personalized content variant */
-type PersonalizedVariant = {
+type PersonalizedVariant<TCriteria = VariantMatchCriteria> = {
     /** A unique identifier for this variation */
     id: string;
     /** Match criteria for this variation */
-    pz?: VariantMatchCriteria;
+    pz?: TCriteria;
 };
 /** The result of computing personalized content from variations */
 type PersonalizedResult<TVariant> = {
@@ -971,6 +1038,7 @@ type PersonalizedResult<TVariant> = {
     personalized: boolean;
     /** Matching variations */
     variations: Array<TVariant & {
+        /** Whether the visitor is part of this variation's local control group (also true if part of global control group) */
         control: boolean;
     }>;
 };
@@ -983,6 +1051,10 @@ type TestVariant = {
      * If not provided, this variant will be selected in equal proportion to other variants without an explicit distribution.
      */
     testDistribution?: number;
+    /** Whether this variant is a control variant.
+     * Can be undefined for backward compatibility with older versions of the SDK which were not explicitly setting the control flag.
+     */
+    control?: boolean;
 };
 /** The result of computing an A/B test result */
 type TestResult<TVariant> = {
@@ -995,25 +1067,38 @@ type TestResult<TVariant> = {
      */
     variantAssigned: boolean;
 };
-
-type PersonalizeOptions<TVariant> = {
+interface PersonalizeOptions<TVariant> {
+    /** Name of placement (sent to analytics) */
+    name: string;
+    /** Possible variations to place  */
+    variations: Iterable<TVariant>;
+    /** Maximum number of variants to place (default: 1) */
+    take?: number;
+    /** Name of the personalization selection algorithm to use. Defaults to top-down criteria when not specified. */
+    algorithm?: string;
+    /** Composition metadata where the personalization is being rendered for analytics tracking */
+    compositionMetadata?: CompositionMetadata;
+}
+interface PersonalizationSelectionAlgorithmOptions<TCriteria, TVariant extends PersonalizedVariant<TCriteria> = PersonalizedVariant<TCriteria>> {
     /** Name of placement (sent to analytics) */
     name: string;
-    /** Possible variants to place  */
+    /** Possible variations to place  */
     variations: Iterable<TVariant>;
     /** Maximum number of variants to place (default: 1) */
     take?: number;
+    /** Callback for logging messages */
     onLogMessage?: (message: LogMessage) => void;
-};
-declare function personalizeVariations<TVariant extends PersonalizedVariant>({ name, context, variations, take, onLogMessage, }: PersonalizeOptions<TVariant> & {
+    /** Context instance */
     context: Context;
-}): PersonalizedResult<TVariant>;
+}
 
 type TestOptions<TVariant extends TestVariant> = {
     /** The name of the test that is being run, must be included in the manifest. */
     name: string;
     /** Variations that are being tested. */
     variations: TVariant[];
+    /** Composition metadata where the personalization is being rendered for analytics tracking */
+    compositionMetadata?: CompositionMetadata;
 };
 declare const testVariations: <TVariant extends TestVariant>({ name, context, variations, onLogMessage, }: TestOptions<TVariant> & {
     context: Context;
@@ -1022,18 +1107,31 @@ declare const testVariations: <TVariant extends TestVariant>({ name, context, va
 
 declare const CONTEXTUAL_EDITING_TEST_NAME = "contextual_editing_test";
 declare const CONTEXTUAL_EDITING_TEST_SELECTED_VARIANT_ID = "contextual_editing_test_selected_variant";
+type PersonalizationSelectionAlgorithm<TCriteria = unknown> = (options: PersonalizationSelectionAlgorithmOptions<TCriteria>) => PersonalizedResult<PersonalizedVariant<TCriteria>>;
+type PersonalizationSelectionAlgorithms<TCriteria = unknown> = Record<string, PersonalizationSelectionAlgorithm<TCriteria>>;
 /**
  * Defines a plugin for Uniform Context.
  * The plugin should attach event handlers in its creation function.
  * @returns A function that detaches any event handlers when called
  */
 type ContextPlugin = {
+    /** Defines a log drain for the plugin, which all log messages are sent to */
     logDrain?: LogDrain;
+    /** Initializes the plugin (attach event handlers here if needed) */
     init?: (context: Context) => () => void;
+    /** Plugin-specific actions to perform when a user is forgotten */
     forget?: () => Promise<void> | void;
-    update?: (newData: Partial<ContextState>) => Promise<void> | void;
+    /** Plugin-specific actions to perform when the visitor context is updated, second parameter is the recalculated scores after the update */
+    update?: (newData: Partial<ContextState>, recalculatedScores: ScoreVector) => Promise<void> | void;
+    /**
+     * Allows the plugin to register named personalization selection algorithms
+     *
+     * Important: the `default` and `strongestMatch` algorithms are automatically registered.
+     * We strongly advise against replacing these.
+     */
+    personalizationSelectionAlgorithms?: PersonalizationSelectionAlgorithms<any>;
 };
-type ContextOptions = {
+interface ContextOptions extends Omit<VisitorDataStoreOptions, 'manifest' | 'onServerTransitionScoresReceived'> {
     /** The Context Manifest to load (from the Context API) */
     manifest: ManifestV2;
     /**
@@ -1050,16 +1148,19 @@ type ContextOptions = {
      * `true`: personalization is not run at all unless storage consent is given
      */
     requireConsentForPersonalization?: boolean;
-} & Omit<VisitorDataStoreOptions, 'manifest' | 'onServerTransitionScoresReceived'>;
+}
+type PersonalizationEventVariantId = {
+    /** The variant ID that was selected */
+    id: string;
+    /** Whether the visitor is part of this variant's local control group (also true if part of global control group) */
+    control: boolean;
+};
 /** Emitted when a personalization runs */
 type PersonalizationEvent = {
     /** Name of the personalized placement */
     name: string;
     /** Selected variant ID(s) */
-    variantIds: {
-        id: string;
-        control: boolean;
-    }[];
+    variantIds: PersonalizationEventVariantId[];
     /** Whether the user was part of the control group (and did not receive any personalization) */
     control: boolean | undefined;
     /**
@@ -1068,6 +1169,12 @@ type PersonalizationEvent = {
      * False: the variant(s) selected were the same as a previous evaluation of this placement.
      */
     changed: boolean;
+    /**
+     * Contains information about the composition that contains personalization wrapper component,
+     * which triggered the personalization event.
+     * Only references top level root composition after pattern resolutions.
+     */
+    compositionMetadata?: CompositionMetadata;
 };
 /** Emitted event when an A/B test runs */
 type TestEvent = {
@@ -1075,12 +1182,22 @@ type TestEvent = {
     name: string;
     /** ID of the variant that was selected */
     variantId: string | undefined;
+    /**
+     * Whether the variant is part of the control group.
+     */
+    control: boolean;
     /**
      * Whether the test variant was newly assigned to the visitor.
      * True: variant was assigned to the visitor for the first time.
      * False: variant was already assigned to the visitor and is being reused.
      */
     variantAssigned: boolean;
+    /**
+     * Contains information about the composition that contains A/B test wrapper component,
+     * which triggered the A/B test event.
+     * Only references top level root composition after pattern resolutions.
+     */
+    compositionMetadata?: CompositionMetadata;
 };
 type ContextEvents = {
     /**
@@ -1104,6 +1221,8 @@ type ContextEvents = {
     testResult: TestEvent;
     /** Personalization variants have been selected */
     personalizationResult: PersonalizationEvent;
+    /** Composition metadata has been set/updated, usually happens when new composition is being rendered during client-side navigation for example */
+    canvasDataUpdated: CompositionMetadata;
 };
 interface ContextInstance {
     get scores(): Readonly<ScoreVector>;
@@ -1113,7 +1232,7 @@ interface ContextInstance {
     setTestVariantId(testName: string, variantId: string): void;
     log(...message: LogMessage): void;
     test<TVariant extends TestVariant>(options: TestOptions<TVariant>): TestResult<TVariant>;
-    personalize<TVariant extends PersonalizedVariant>(options: PersonalizeOptions<TVariant>): PersonalizedResult<TVariant>;
+    personalize<TVariant extends PersonalizedVariant<any>>(options: PersonalizeOptions<TVariant>): PersonalizedResult<TVariant>;
     forget(fromAllDevices: boolean): Promise<void>;
     getServerToClientTransitionState(): ServerToClientTransitionState;
     readonly manifest: ManifestInstance;
@@ -1125,6 +1244,14 @@ interface ContextInstance {
     internal_processTestEvent(event: TestEvent): void;
     /** @deprecated */
     internal_processPersonalizationEvent(event: PersonalizationEvent): void;
+    /**
+     * Gets the current canvas data
+     */
+    getCompositionMetadata(): Readonly<CompositionMetadata | undefined>;
+    /**
+     * Updates the canvas data and emits a canvasDataUpdated event
+     */
+    updateCompositionMetadata(newData: CompositionMetadata): Promise<void>;
 }
 declare class Context implements ContextInstance {
     #private;
@@ -1178,7 +1305,7 @@ declare class Context implements ContextInstance {
     /** Executes an A/B test with a given set of variants, showing the visitor's assigned variant (or selecting one to assign, if none is set yet) */
     test<TVariant extends TestVariant>(options: TestOptions<TVariant>): TestResult<TVariant>;
     /** Executes a personalized placement with a given set of variants */
-    personalize<TVariant extends PersonalizedVariant>(options: PersonalizeOptions<TVariant>): PersonalizedResult<TVariant>;
+    personalize<TVariant extends PersonalizedVariant<any>>(options: PersonalizeOptions<TVariant>): PersonalizedResult<TVariant>;
     /**
      * Forgets the visitor's data and resets the Context to its initial state.
      * @param fromAllDevices for an identified user, whether to delete all their data (for the entire account) - true, or data for this device (sign out) - false
@@ -1194,6 +1321,14 @@ declare class Context implements ContextInstance {
     internal_processTestEvent(event: TestEvent): void;
     /** @deprecated */
     internal_processPersonalizationEvent(event: PersonalizationEvent): void;
+    /**
+     * Gets the current canvas data
+     */
+    getCompositionMetadata(): Readonly<CompositionMetadata | undefined>;
+    /**
+     * Updates the canvas data and emits a canvasDataUpdated event
+     */
+    updateCompositionMetadata(newData: CompositionMetadata): Promise<void>;
 }
 
 /**
@@ -1265,4 +1400,4 @@ declare global {
     }
 }
 
-export { type AggregateDimensionInput as $, type AggregateDimension as A, type MessageFunc as B, type ContextPlugin as C, type DecayFunction as D, type LogMessageSingle as E, type LogMessageGroup as F, ManifestInstance as G, GroupCriteriaEvaluator as H, type CriteriaEvaluatorResult as I, type CriteriaEvaluatorParameters as J, type SignalData as K, type LogDrain as L, type MessageCategory as M, type ManifestV2 as N, type OutputSeverity as O, type PersonalizationEvent as P, type Quirks as Q, type PersonalizationManifest as R, type ScoreVector as S, TransitionDataStore as T, type Signal as U, type VisitorData as V, type SignalCriteriaGroup as W, type SignalCriteria as X, type EnrichmentCategory as Y, type NumberMatch as Z, type TestDefinition as _, type StorageCommands as a, type TestOptions as a0, testVariations as a1, type DimensionMatch as a2, type PersonalizeOptions as a3, personalizeVariations as a4, type BehaviorTag as a5, type PersonalizedVariant as a6, type PersonalizedResult as a7, type TestVariant as a8, type TestResult as a9, type ContextStateUpdate as aA, type GoalStateUpdate as aB, type paths as aC, type StorageCommand as aa, type SetGoalCommand as ab, type ModifyScoreCommand as ac, type ModifySessionScoreCommand as ad, type SetConsentCommand as ae, type SetQuirkCommand as af, type SetTestCommand as ag, type IdentifyCommand as ah, type SetControlGroupCommand as ai, type SetPersonalizeVariantControlCommand as aj, areCommandsEqual as ak, type ServerToClientTransitionState as al, SERVER_STATE_ID as am, type TransitionDataStoreEvents as an, type DecayOptions as ao, type VisitorDataStoreOptions as ap, type VisitorDataStoreEvents as aq, VisitorDataStore as ar, type Tests as as, type Goals as at, type EnrichmentData as au, type PersonalizeControlVariant as av, type PersonalizeVariants as aw, type EventData as ax, emptyVisitorData as ay, type ContextState as az, type TransitionDataStoreOptions as b, type CriteriaEvaluator as c, type StringMatch as d, type VariantMatchCriteria as e, type LogMessage as f, type DevToolsEvents as g, CONTEXTUAL_EDITING_TEST_NAME as h, CONTEXTUAL_EDITING_TEST_SELECTED_VARIANT_ID as i, type ContextOptions as j, type TestEvent as k, type ContextEvents as l, type ContextInstance as m, Context as n, type DevToolsUiVersion as o, type DevToolsState as p, type DevToolsActions as q, type DevToolsEvent as r, type DevToolsLogEvent as s, type DevToolsDataEvent as t, type DevToolsHelloEvent as u, type DevToolsUpdateEvent as v, type DevToolsRawCommandsEvent as w, type DevToolsForgetEvent as x, type LogMessages as y, type Severity as z };
+export { type ManifestV2 as $, type AggregateDimension as A, type DevToolsLogEvent as B, type ContextPlugin as C, type DecayFunction as D, type DevToolsDataEvent as E, type DevToolsHelloEvent as F, type DevToolsUpdateEvent as G, type DevToolsRawCommandsEvent as H, type DevToolsForgetEvent as I, type LogMessages as J, type Severity as K, type LogDrain as L, type MessageCategory as M, type MessageFunc as N, type OutputSeverity as O, type PersonalizedVariant as P, type Quirks as Q, type LogMessageSingle as R, type ScoreVector as S, TransitionDataStore as T, type LogMessageGroup as U, type VisitorData as V, ManifestInstance as W, GroupCriteriaEvaluator as X, type CriteriaEvaluatorResult as Y, type CriteriaEvaluatorParameters as Z, type SignalData as _, type StorageCommands as a, type PersonalizationManifest as a0, type Signal as a1, type SignalCriteriaGroup as a2, type SignalCriteria as a3, type EnrichmentCategory as a4, type NumberMatch as a5, type TestDefinition as a6, type AggregateDimensionInput as a7, type TestOptions as a8, testVariations as a9, type EnrichmentData as aA, type PersonalizeControlVariant as aB, type PersonalizeVariants as aC, type EventData as aD, emptyVisitorData as aE, type CompositionMetadata as aF, type ContextState as aG, type ContextStateUpdate as aH, type GoalStateUpdate as aI, type paths as aJ, type VariationMatchMetadata as aa, type DimensionMatch as ab, type QuirkMatch as ac, type BehaviorTag as ad, type TestVariant as ae, type TestResult as af, type StorageCommand as ag, type SetGoalCommand as ah, type ModifyScoreCommand as ai, type ModifySessionScoreCommand as aj, type SetConsentCommand as ak, type SetQuirkCommand as al, type SetTestCommand as am, type IdentifyCommand as an, type SetControlGroupCommand as ao, type SetPersonalizeVariantControlCommand as ap, areCommandsEqual as aq, type ServerToClientTransitionState as ar, SERVER_STATE_ID as as, type TransitionDataStoreEvents as at, type DecayOptions as au, type VisitorDataStoreOptions as av, type VisitorDataStoreEvents as aw, VisitorDataStore as ax, type Tests as ay, type Goals as az, type TransitionDataStoreOptions as b, type CriteriaEvaluator as c, type StringMatch as d, type VariantMatchCriteria as e, type LogMessage as f, type PersonalizeOptions as g, Context as h, type PersonalizedResult as i, type VariationMatchDimensionCriteria as j, type PersonalizationSelectionAlgorithmOptions as k, type DevToolsEvents as l, CONTEXTUAL_EDITING_TEST_NAME as m, CONTEXTUAL_EDITING_TEST_SELECTED_VARIANT_ID as n, type PersonalizationSelectionAlgorithm as o, type PersonalizationSelectionAlgorithms as p, type ContextOptions as q, type PersonalizationEventVariantId as r, type PersonalizationEvent as s, type TestEvent as t, type ContextEvents as u, type ContextInstance as v, type DevToolsUiVersion as w, type DevToolsState as x, type DevToolsActions as y, type DevToolsEvent as z };