@contentful/optimization-core 0.1.0-alpha

package/dist/personalization/PersonalizationBase.d.ts

@@ -0,0 +1,184 @@
+import type { ChangeArray, ComponentViewBuilderArgs, IdentifyBuilderArgs, Json, MergeTagEntry, OptimizationData, PageViewBuilderArgs, Profile, ScreenViewBuilderArgs, SelectedPersonalizationArray, TrackBuilderArgs } from '@contentful/optimization-api-client';
+import type { ChainModifiers, Entry, EntrySkeletonType, LocaleCode } from 'contentful';
+import ProductBase from '../ProductBase';
+import { type ResolvedData } from './resolvers';
+/**
+ * These methods assist in resolving values via Resolvers
+ *
+ * @internal
+ * @privateRemarks
+ * This interface exists to document that the included methods should not be
+ * considered static.
+ */
+interface ResolverMethods {
+    /**
+     * Get the specified Custom Flag's value from the supplied changes.
+     * @param name - The name or key of the Custom Flag.
+     * @param changes - Optional changes array.
+     * @returns The current value of the Custom Flag if found.
+     * @remarks
+     * The changes array can be sourced from the data returned when emitting any
+     * personalization event.
+     * */
+    getCustomFlag: (name: string, changes?: ChangeArray) => Json;
+    /**
+     * Resolve a Contentful entry to a personalized variant using the current
+     * or provided selected personalizations.
+     *
+     * @typeParam S - Entry skeleton type.
+     * @typeParam M - Chain modifiers.
+     * @typeParam L - Locale code.
+     * @param entry - The entry to personalize.
+     * @param personalizations - Optional selections.
+     * @returns The resolved entry data.
+     * @remarks
+     * Selected personalizations can be sourced from the data returned when emitting any
+     * personalization event.
+     */
+    personalizeEntry: <S extends EntrySkeletonType, M extends ChainModifiers, L extends LocaleCode>(entry: Entry<S, M, L>, personalizations?: SelectedPersonalizationArray) => ResolvedData<S, M, L>;
+    /**
+     * Resolve a merge tag to a value based on the current (or provided) profile.
+     *
+     * @param embeddedEntryNodeTarget - The merge‑tag entry node to resolve.
+     * @param profile - Optional profile.
+     * @returns The resolved value (type depends on the tag).
+     * @remarks
+     * Merge tags are references to profile data that can be substituted into content. The
+     * profile can be sourced from the data returned when emitting any personalization event.
+     */
+    getMergeTagValue: (embeddedEntryNodeTarget: MergeTagEntry, profile?: Profile) => unknown;
+}
+/**
+ * Internal base for personalization products.
+ *
+ * @internal
+ * @remarks
+ * Concrete implementations should extend this class to expose public methods for
+ * identify, page, and track events. This base wires in shared singleton
+ * resolvers used to fetch/resolve personalized data.
+ */
+declare abstract class PersonalizationBase extends ProductBase implements ResolverMethods {
+    /**
+     * Static {@link FlagsResolver | resolver} for evaluating personalized
+     * custom flags.
+     */
+    readonly flagsResolver: {
+        resolve(changes?: ChangeArray): import("@contentful/optimization-api-schemas").Flags;
+    };
+    /**
+     * Static {@link MergeTagValueResolver | resolver} that returns values
+     * sourced from a user profile based on a Contentful Merge Tag entry.
+     */
+    readonly mergeTagValueResolver: {
+        isMergeTagEntry(embeddedEntryNodeTarget: unknown): embeddedEntryNodeTarget is MergeTagEntry;
+        normalizeSelectors(id: string): string[];
+        getValueFromProfile(id: string, profile?: Profile): string | undefined;
+        resolve(mergeTagEntry: MergeTagEntry | undefined, profile?: Profile): string | undefined;
+    };
+    /**
+     * Static {@link PersonalizedEntryResolver | resolver } for personalized
+     * Contentful entries (e.g., entry variants targeted to a profile audience).
+     *
+     * @remarks
+     * Used by higher-level personalization flows to materialize entry content
+     * prior to event emission.
+     */
+    readonly personalizedEntryResolver: {
+        getPersonalizationEntry({ personalizedEntry, selectedPersonalizations, }: {
+            personalizedEntry: import("@contentful/optimization-api-schemas").PersonalizedEntry;
+            selectedPersonalizations: SelectedPersonalizationArray;
+        }, skipValidation?: boolean): import("@contentful/optimization-api-schemas").PersonalizationEntry | undefined;
+        getSelectedPersonalization({ personalizationEntry, selectedPersonalizations, }: {
+            personalizationEntry: import("@contentful/optimization-api-schemas").PersonalizationEntry;
+            selectedPersonalizations: SelectedPersonalizationArray;
+        }, skipValidation?: boolean): import("@contentful/optimization-api-schemas").SelectedPersonalization | undefined;
+        getSelectedVariant({ personalizedEntry, personalizationEntry, selectedVariantIndex, }: {
+            personalizedEntry: import("@contentful/optimization-api-schemas").PersonalizedEntry;
+            personalizationEntry: import("@contentful/optimization-api-schemas").PersonalizationEntry;
+            selectedVariantIndex: number;
+        }, skipValidation?: boolean): import("@contentful/optimization-api-schemas").EntryReplacementVariant | undefined;
+        getSelectedVariantEntry<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = string>({ personalizationEntry, selectedVariant, }: {
+            personalizationEntry: import("@contentful/optimization-api-schemas").PersonalizationEntry;
+            selectedVariant: import("@contentful/optimization-api-schemas").EntryReplacementVariant;
+        }, skipValidation?: boolean): Entry<S, M, L> | undefined;
+        resolve<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = string>(entry: Entry<S, M, L>, selectedPersonalizations?: SelectedPersonalizationArray): ResolvedData<S, M, L>;
+    };
+    /**
+     * Get the specified Custom Flag's value from the supplied changes.
+     * @param name - The name/key of the Custom Flag.
+     * @param changes - Optional changes array.
+     * @returns The current value of the Custom Flag if found.
+     * @remarks
+     * The changes array can be sourced from the data returned when emitting any
+     * personalization event.
+     * */
+    getCustomFlag(name: string, changes?: ChangeArray): Json;
+    /**
+     * Resolve a Contentful entry to a personalized variant using the current
+     * or provided selected personalizations.
+     *
+     * @typeParam S - Entry skeleton type.
+     * @typeParam M - Chain modifiers.
+     * @typeParam L - Locale code.
+     * @param entry - The entry to personalize.
+     * @param personalizations - Optional selected personalizations.
+     * @returns The resolved entry data.
+     * @remarks
+     * Selected personalizations can be sourced from the data returned when emitting any
+     * personalization event.
+     */
+    personalizeEntry<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = LocaleCode>(entry: Entry<S, M, L>, personalizations?: SelectedPersonalizationArray): ResolvedData<S, M, L>;
+    /**
+     * Resolve a merge tag to a value based on the current (or provided) profile.
+     *
+     * @param embeddedEntryNodeTarget - The merge tag entry node to resolve.
+     * @param profile - Optional profile.
+     * @returns The resolved value (type depends on the tag).
+     * @remarks
+     * Merge tags are references to profile data that can be substituted into content. The
+     * profile can be sourced from the data returned when emitting any personalization event.
+     */
+    getMergeTagValue(embeddedEntryNodeTarget: MergeTagEntry, profile?: Profile): unknown;
+    /**
+     * Identify the current profile/visitor to associate traits with a profile.
+     *
+     * @param payload - Identify builder payload.
+     * @returns The resulting {@link OptimizationData} for the identified user if the device is online.
+     */
+    abstract identify(payload: IdentifyBuilderArgs): Promise<OptimizationData | undefined>;
+    /**
+     * Record a page view.
+     *
+     * @param payload - Page view builder payload.
+     * @returns The evaluated {@link OptimizationData} for this page view if the device is online.
+     */
+    abstract page(payload: PageViewBuilderArgs): Promise<OptimizationData | undefined>;
+    /**
+     * Record a screen view.
+     *
+     * @param payload - Screen view builder payload.
+     * @returns The evaluated {@link OptimizationData} for this screen view if the device is online.
+     */
+    abstract screen(payload: ScreenViewBuilderArgs): Promise<OptimizationData | undefined>;
+    /**
+     * Record a custom track event.
+     *
+     * @param payload - Track builder payload.
+     * @returns The evaluated {@link OptimizationData} for this event if the device is online.
+     */
+    abstract track(payload: TrackBuilderArgs): Promise<OptimizationData | undefined>;
+    /**
+     * Record a "sticky" component view.
+     *
+     * @param payload - "Sticky" component view builder payload.
+     * @returns The evaluated {@link OptimizationData} for this component view if the device is online.
+     * @remarks
+     * This method is intended to be called only when a component is considered
+     * "sticky".
+     * @privateRemarks
+     * Duplication prevention should be handled in Stateful implementations.
+     */
+    abstract trackComponentView(payload: ComponentViewBuilderArgs, duplicationScope?: string): Promise<OptimizationData | undefined>;
+}
+export default PersonalizationBase;
+//# sourceMappingURL=PersonalizationBase.d.ts.map

package/dist/personalization/PersonalizationBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersonalizationBase.d.ts","sourceRoot":"","sources":["../../src/personalization/PersonalizationBase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,wBAAwB,EACxB,mBAAmB,EACnB,IAAI,EACJ,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,OAAO,EACP,qBAAqB,EACrB,4BAA4B,EAC5B,gBAAgB,EACjB,MAAM,qCAAqC,CAAA;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACtF,OAAO,WAAW,MAAM,gBAAgB,CAAA;AACxC,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,aAAa,CAAA;AAEpB;;;;;;;GAOG;AACH,UAAU,eAAe;IACvB;;;;;;;;SAQK;IACL,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,IAAI,CAAA;IAE5D;;;;;;;;;;;;;OAaG;IACH,gBAAgB,EAAE,CAAC,CAAC,SAAS,iBAAiB,EAAE,CAAC,SAAS,cAAc,EAAE,CAAC,SAAS,UAAU,EAC5F,KAAK,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACrB,gBAAgB,CAAC,EAAE,4BAA4B,KAC5C,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IAE1B;;;;;;;;;OASG;IACH,gBAAgB,EAAE,CAAC,uBAAuB,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,OAAO,CAAA;CACzF;AAED;;;;;;;;GAQG;AACH,uBAAe,mBAAoB,SAAQ,WAAY,YAAW,eAAe;IAC/E;;;OAGG;IACH,QAAQ,CAAC,aAAa;;MAAgB;IAEtC;;;OAGG;IACH,QAAQ,CAAC,qBAAqB;;;;;MAAwB;IAEtD;;;;;;;OAOG;IACH,QAAQ,CAAC,yBAAyB;;;;;;;;;;;;;;;;;;;MAA4B;IAE9D;;;;;;;;SAQK;IACL,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI;IAIxD;;;;;;;;;;;;;OAaG;IACH,gBAAgB,CACd,CAAC,SAAS,iBAAiB,EAC3B,CAAC,SAAS,cAAc,GAAG,cAAc,EACzC,CAAC,SAAS,UAAU,GAAG,UAAU,EACjC,KAAK,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,gBAAgB,CAAC,EAAE,4BAA4B,GAAG,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAIhG;;;;;;;;;OASG;IACH,gBAAgB,CAAC,uBAAuB,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO;IAIpF;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAEtF;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAElF;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAEtF;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAEhF;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,kBAAkB,CACzB,OAAO,EAAE,wBAAwB,EACjC,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;CACzC;AAED,eAAe,mBAAmB,CAAA"}

package/dist/personalization/PersonalizationBase.js

@@ -0,0 +1,76 @@
+import ProductBase from '../ProductBase';
+import { FlagsResolver, MergeTagValueResolver, PersonalizedEntryResolver, } from './resolvers';
+/**
+ * Internal base for personalization products.
+ *
+ * @internal
+ * @remarks
+ * Concrete implementations should extend this class to expose public methods for
+ * identify, page, and track events. This base wires in shared singleton
+ * resolvers used to fetch/resolve personalized data.
+ */
+class PersonalizationBase extends ProductBase {
+    /**
+     * Static {@link FlagsResolver | resolver} for evaluating personalized
+     * custom flags.
+     */
+    flagsResolver = FlagsResolver;
+    /**
+     * Static {@link MergeTagValueResolver | resolver} that returns values
+     * sourced from a user profile based on a Contentful Merge Tag entry.
+     */
+    mergeTagValueResolver = MergeTagValueResolver;
+    /**
+     * Static {@link PersonalizedEntryResolver | resolver } for personalized
+     * Contentful entries (e.g., entry variants targeted to a profile audience).
+     *
+     * @remarks
+     * Used by higher-level personalization flows to materialize entry content
+     * prior to event emission.
+     */
+    personalizedEntryResolver = PersonalizedEntryResolver;
+    /**
+     * Get the specified Custom Flag's value from the supplied changes.
+     * @param name - The name/key of the Custom Flag.
+     * @param changes - Optional changes array.
+     * @returns The current value of the Custom Flag if found.
+     * @remarks
+     * The changes array can be sourced from the data returned when emitting any
+     * personalization event.
+     * */
+    getCustomFlag(name, changes) {
+        return FlagsResolver.resolve(changes)[name];
+    }
+    /**
+     * Resolve a Contentful entry to a personalized variant using the current
+     * or provided selected personalizations.
+     *
+     * @typeParam S - Entry skeleton type.
+     * @typeParam M - Chain modifiers.
+     * @typeParam L - Locale code.
+     * @param entry - The entry to personalize.
+     * @param personalizations - Optional selected personalizations.
+     * @returns The resolved entry data.
+     * @remarks
+     * Selected personalizations can be sourced from the data returned when emitting any
+     * personalization event.
+     */
+    personalizeEntry(entry, personalizations) {
+        return PersonalizedEntryResolver.resolve(entry, personalizations);
+    }
+    /**
+     * Resolve a merge tag to a value based on the current (or provided) profile.
+     *
+     * @param embeddedEntryNodeTarget - The merge tag entry node to resolve.
+     * @param profile - Optional profile.
+     * @returns The resolved value (type depends on the tag).
+     * @remarks
+     * Merge tags are references to profile data that can be substituted into content. The
+     * profile can be sourced from the data returned when emitting any personalization event.
+     */
+    getMergeTagValue(embeddedEntryNodeTarget, profile) {
+        return MergeTagValueResolver.resolve(embeddedEntryNodeTarget, profile);
+    }
+}
+export default PersonalizationBase;
+//# sourceMappingURL=PersonalizationBase.js.map

package/dist/personalization/PersonalizationBase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersonalizationBase.js","sourceRoot":"","sources":["../../src/personalization/PersonalizationBase.ts"],"names":[],"mappings":"AAcA,OAAO,WAAW,MAAM,gBAAgB,CAAA;AACxC,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,yBAAyB,GAE1B,MAAM,aAAa,CAAA;AAsDpB;;;;;;;;GAQG;AACH,MAAe,mBAAoB,SAAQ,WAAW;IACpD;;;OAGG;IACM,aAAa,GAAG,aAAa,CAAA;IAEtC;;;OAGG;IACM,qBAAqB,GAAG,qBAAqB,CAAA;IAEtD;;;;;;;OAOG;IACM,yBAAyB,GAAG,yBAAyB,CAAA;IAE9D;;;;;;;;SAQK;IACL,aAAa,CAAC,IAAY,EAAE,OAAqB;QAC/C,OAAO,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAA;IAC7C,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,gBAAgB,CAId,KAAqB,EAAE,gBAA+C;QACtE,OAAO,yBAAyB,CAAC,OAAO,CAAU,KAAK,EAAE,gBAAgB,CAAC,CAAA;IAC5E,CAAC;IAED;;;;;;;;;OASG;IACH,gBAAgB,CAAC,uBAAsC,EAAE,OAAiB;QACxE,OAAO,qBAAqB,CAAC,OAAO,CAAC,uBAAuB,EAAE,OAAO,CAAC,CAAA;IACxE,CAAC;CAiDF;AAED,eAAe,mBAAmB,CAAA"}

package/dist/personalization/PersonalizationStateful.d.ts

@@ -0,0 +1,226 @@
+import { type InsightsEvent as AnalyticsEvent, type ChangeArray, type ComponentViewBuilderArgs, type Flags, type IdentifyBuilderArgs, type Json, type MergeTagEntry, type OptimizationData, type PageViewBuilderArgs, ExperienceEvent as PersonalizationEvent, type Profile, type ScreenViewBuilderArgs, type SelectedPersonalizationArray, type TrackBuilderArgs } from '@contentful/optimization-api-client';
+import type { ChainModifiers, Entry, EntrySkeletonType, LocaleCode } from 'contentful';
+import type { ConsentGuard } from '../Consent';
+import type { ProductBaseOptions, ProductConfig } from '../ProductBase';
+import { type Observable } from '../signals';
+import PersonalizationBase from './PersonalizationBase';
+import type { ResolvedData } from './resolvers';
+/**
+ * Default state values for {@link PersonalizationStateful} applied at construction time.
+ *
+ * @public
+ */
+export interface PersonalizationProductConfigDefaults {
+    /** Whether personalization is allowed by default. */
+    consent?: boolean;
+    /** Initial diff of changes produced by the service. */
+    changes?: ChangeArray;
+    /** Default active profile used for personalization. */
+    profile?: Profile;
+    /** Preselected personalization variants (e.g., winning treatments). */
+    personalizations?: SelectedPersonalizationArray;
+}
+/**
+ * Configuration for {@link PersonalizationStateful}.
+ *
+ * @public
+ */
+export interface PersonalizationProductConfig extends ProductConfig {
+    /** Default signal values applied during initialization. */
+    defaults?: PersonalizationProductConfigDefaults;
+    /**
+     * Function used to obtain an anonymous user identifier.
+     *
+     * @remarks
+     * If a `getAnonymousId` function has been provided, the returned value will
+     * take precedence over the `id` property of the current {@link Profile}
+     * signal value
+     *
+     * @returns A string identifier, or `undefined` if no anonymous ID is available.
+     */
+    getAnonymousId?: () => string | undefined;
+}
+/**
+ * Observables exposed by {@link PersonalizationStateful} that mirror internal signals.
+ *
+ * @public
+ */
+export interface PersonalizationStates {
+    /** Observable stream of the latest {@link AnalyticsEvent} or {@link PersonalizationEvent} (or `undefined`). */
+    eventStream: Observable<AnalyticsEvent | PersonalizationEvent | undefined>;
+    /** Live view of effective flags for the current profile (if available). */
+    flags: Observable<Flags | undefined>;
+    /** Live view of the current profile. */
+    profile: Observable<Profile | undefined>;
+    /** Live view of selected personalizations (variants). */
+    personalizations: Observable<SelectedPersonalizationArray | undefined>;
+}
+/**
+ * Options for configuring {@link PersonalizationStateful} functionality.
+ *
+ * @public
+ * @see {@link ProductBaseOptions}
+ */
+export type PersonalizationStatefulOptions = ProductBaseOptions & {
+    /** Configuration specific to the Personalization product */
+    config?: PersonalizationProductConfig;
+};
+/**
+ * Stateful personalization product that manages consent, profile, flags, and
+ * selected variants while emitting Experience events and updating state.
+ *
+ * @public
+ * @remarks
+ * The class maintains reactive signals and exposes read‑only observables via
+ * {@link PersonalizationStateful.states}. Events are validated via schema parsers and
+ * run through interceptors before being submitted. Resulting state is merged
+ * back into signals.
+ */
+declare class PersonalizationStateful extends PersonalizationBase implements ConsentGuard {
+    /** In‑memory queue for offline events keyed by profile. */
+    private readonly offlineQueue;
+    /** Exposed observable state references. */
+    readonly states: PersonalizationStates;
+    /**
+     * Function that provides an anonymous ID when available.
+     *
+     * @internal
+     */
+    getAnonymousId: () => string | undefined;
+    /**
+     * Create a new stateful personalization instance.
+     *
+     * @param options - Options to configure the personalization product for stateful environments.
+     */
+    constructor(options: PersonalizationStatefulOptions);
+    /**
+     * Reset stateful signals managed by this product.
+     *
+     * @remarks
+     * Clears `changes`, `profile`, and selected `personalizations`.
+     */
+    reset(): void;
+    /**
+     * Get the specified Custom Flag's value (derived from the signal).
+     * @param name - The name or key of the Custom Flag.
+     * @returns The current value of the Custom Flag if found.
+     * */
+    getCustomFlag(name: string, changes?: ChangeArray | undefined): Json;
+    /**
+     * Resolve a Contentful entry to a personalized variant using the current
+     * or provided selections.
+     *
+     * @typeParam S - Entry skeleton type.
+     * @typeParam M - Chain modifiers.
+     * @typeParam L - Locale code.
+     * @param entry - The entry to personalize.
+     * @param personalizations - Optional selections; defaults to the current signal value.
+     * @returns The resolved entry data.
+     */
+    personalizeEntry<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = LocaleCode>(entry: Entry<S, M, L>, personalizations?: SelectedPersonalizationArray | undefined): ResolvedData<S, M, L>;
+    /**
+     * Resolve a merge tag to a value based on the current (or provided) profile.
+     *
+     * @param embeddedEntryNodeTarget - The merge‑tag entry node to resolve.
+     * @param profile - Optional profile; defaults to the current signal value.
+     * @returns The resolved value (type depends on the tag).
+     * @remarks
+     * Merge tags are references to profile data that can be substituted into content.
+     */
+    getMergeTagValue(embeddedEntryNodeTarget: MergeTagEntry, profile?: Profile | undefined): unknown;
+    /**
+     * Determine whether the named operation is permitted based on consent and
+     * allowed event type configuration.
+     *
+     * @param name - Method name; `trackComponentView` is normalized to
+     * `'component'` for allow‑list checks.
+     * @returns `true` if the operation is permitted; otherwise `false`.
+     */
+    hasConsent(name: string): boolean;
+    /**
+     * Hook invoked when an operation is blocked due to missing consent.
+     *
+     * @param name - The blocked operation name.
+     * @param payload - The original arguments supplied to the operation.
+     */
+    onBlockedByConsent(name: string, payload: unknown[]): void;
+    /**
+     * Guard used to suppress duplicate component view events for the same
+     * component based on a duplication key and the component identifier.
+     *
+     * @param _name - Operation name (unused).
+     * @param payload - Tuple `[builderArgs, duplicationScope]`.
+     * @returns `true` if the event is NOT a duplicate and should proceed.
+     */
+    isNotDuplicated(_name: string, payload: [ComponentViewBuilderArgs, string]): boolean;
+    /**
+     * Hook invoked when an operation is blocked by the duplication guard.
+     *
+     * @param _name - The blocked operation name (unused).
+     * @param payload - The original arguments supplied to the operation.
+     */
+    onBlockedByDuplication(_name: string, payload: unknown[]): void;
+    /**
+     * Identify the current profile/visitor to associate traits with a profile
+     * and update optimization state.
+     *
+     * @param payload - Identify builder payload.
+     * @returns The resulting {@link OptimizationData} for the identified user.
+     */
+    identify(payload: IdentifyBuilderArgs): Promise<OptimizationData | undefined>;
+    /**
+     * Record a page view and update optimization state.
+     *
+     * @param payload - Page view builder payload.
+     * @returns The evaluated {@link OptimizationData} for this page view.
+     */
+    page(payload: PageViewBuilderArgs): Promise<OptimizationData | undefined>;
+    /**
+     * Record a screen view and update optimization state.
+     *
+     * @param payload - Screen view builder payload.
+     * @returns The evaluated {@link OptimizationData} for this screen view.
+     */
+    screen(payload: ScreenViewBuilderArgs): Promise<OptimizationData | undefined>;
+    /**
+     * Record a custom track event and update optimization state.
+     *
+     * @param payload - Track builder payload.
+     * @returns The evaluated {@link OptimizationData} for this event.
+     */
+    track(payload: TrackBuilderArgs): Promise<OptimizationData | undefined>;
+    trackComponentView(payload: ComponentViewBuilderArgs, _duplicationScope?: string): Promise<OptimizationData | undefined>;
+    /**
+     * Intercept, validate, and place an event into the offline eventd queue; then
+     * trigger a size‑based flush if necessary.
+     *
+     * @param event - The event to enqueue.
+     */
+    private sendOrEnqueueEvent;
+    /**
+     * Flush the offline queue
+     */
+    flush(): Promise<void>;
+    /**
+     * Submit events to the Experience API, updating output signals with the
+     * returned state.
+     *
+     * @param events - The events to submit.
+     * @returns The {@link OptimizationData} returned by the service.
+     * @internal
+     * @privateRemarks
+     * If a `getAnonymousId` function has been provided, the returned value will
+     * take precedence over the `id` property of the current {@link Profile}
+     * signal value
+     */
+    private upsertProfile;
+    /**
+     * Apply returned optimization state to local signals after interceptor processing.
+     *
+     * @param data - Optimization state returned by the service.
+     * @internal
+     */
+    private updateOutputSignals;
+}
+export default PersonalizationStateful;
+//# sourceMappingURL=PersonalizationStateful.d.ts.map

package/dist/personalization/PersonalizationStateful.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersonalizationStateful.d.ts","sourceRoot":"","sources":["../../src/personalization/PersonalizationStateful.ts"],"names":[],"mappings":"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"}