@contentful/optimization-api-client 0.1.0-alpha

package/dist/builders/EventBuilder.d.ts

@@ -0,0 +1,589 @@
+import { type App, type Channel, type ComponentViewEvent, type IdentifyEvent, type Library, Page, type PageViewEvent, type ScreenViewEvent, type TrackEvent, type UniversalEventProperties } from '@contentful/optimization-api-schemas';
+import * as z from 'zod/mini';
+/**
+ * Configuration options for creating an {@link EventBuilder} instance.
+ *
+ * @public
+ * @remarks
+ * The configuration is typically provided by the host application to adapt
+ * event payloads to the runtime environment (browser, framework, etc.).
+ *
+ * @example
+ * ```ts
+ * const builder = new EventBuilder({
+ *   app: { name: 'my-app', version: '1.0.0' },
+ *   channel: 'web',
+ *   library: { name: '@contentful/optimization-sdk', version: '1.2.3' },
+ *   getLocale: () => navigator.language,
+ *   getPageProperties: () => ({
+ *     path: window.location.pathname,
+ *     url: window.location.href,
+ *     title: document.title,
+ *     query: {},
+ *     referrer: document.referrer,
+ *     search: window.location.search,
+ *   }),
+ * })
+ * ```
+ */
+export interface EventBuilderConfig {
+    /**
+     * The application definition used to attribute events to a specific consumer app.
+     *
+     * @remarks
+     * When not provided, events will not contain app metadata in their context.
+     */
+    app?: App;
+    /**
+     * The channel that identifies where events originate from (e.g. web, mobile).
+     *
+     * @see {@link Channel}
+     */
+    channel: Channel;
+    /**
+     * The client library metadata that is attached to all events.
+     *
+     * @remarks
+     * This is typically used to record the library name and version.
+     */
+    library: Library;
+    /**
+     * Function used to resolve the locale for outgoing events.
+     *
+     * @remarks
+     * If not provided, the builder falls back to the default `'en-US'`. Locale
+     * values supplied directly as arguments to event builder methods take
+     * precedence.
+     *
+     * @returns The locale string (e.g. `'en-US'`), or `undefined` if unavailable.
+     */
+    getLocale?: () => string | undefined;
+    /**
+     * Function that returns the current page properties.
+     *
+     * @remarks
+     * Page properties are currently added to the context of all events, as well
+     * as the `properties` of the page event. When specified, all properties of
+     * the `Page` type are required, but may contain empty values.
+     *
+     * @returns A {@link Page} object containing information about the current page.
+     * @see {@link Page}
+     */
+    getPageProperties?: () => Page;
+    /**
+     * Function used to obtain the current user agent string when applicable.
+     *
+     * @returns A user agent string, or `undefined` if unavailable.
+     */
+    getUserAgent?: () => string | undefined;
+}
+declare const UniversalEventBuilderArgs: z.ZodMiniObject<{
+    campaign: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        source: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        medium: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        term: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        content: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    locale: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    location: z.ZodMiniOptional<z.ZodMiniObject<{
+        coordinates: z.ZodMiniOptional<z.ZodMiniObject<{
+            latitude: z.ZodMiniNumber<number>;
+            longitude: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>;
+        city: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        postalCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        region: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        regionCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        countryCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        continent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        timezone: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    page: z.ZodMiniOptional<z.ZodMiniObject<{
+        path: z.ZodMiniString<string>;
+        query: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+        referrer: z.ZodMiniString<string>;
+        search: z.ZodMiniString<string>;
+        title: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        url: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    screen: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    userAgent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+}, z.core.$strip>;
+/**
+ * Arguments used to construct the universal (shared) portion of all events.
+ *
+ * @public
+ */
+export type UniversalEventBuilderArgs = z.infer<typeof UniversalEventBuilderArgs>;
+declare const ComponentViewBuilderArgs: z.ZodMiniObject<{
+    campaign: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        source: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        medium: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        term: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        content: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    locale: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    location: z.ZodMiniOptional<z.ZodMiniObject<{
+        coordinates: z.ZodMiniOptional<z.ZodMiniObject<{
+            latitude: z.ZodMiniNumber<number>;
+            longitude: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>;
+        city: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        postalCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        region: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        regionCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        countryCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        continent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        timezone: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    page: z.ZodMiniOptional<z.ZodMiniObject<{
+        path: z.ZodMiniString<string>;
+        query: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+        referrer: z.ZodMiniString<string>;
+        search: z.ZodMiniString<string>;
+        title: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        url: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    screen: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    userAgent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    componentId: z.ZodMiniString<string>;
+    experienceId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    variantIndex: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
+    sticky: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+}, z.core.$strip>;
+/**
+ * Arguments for constructing component view events.
+ *
+ * @public
+ */
+export type ComponentViewBuilderArgs = z.infer<typeof ComponentViewBuilderArgs>;
+declare const IdentifyBuilderArgs: z.ZodMiniObject<{
+    campaign: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        source: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        medium: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        term: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        content: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    locale: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    location: z.ZodMiniOptional<z.ZodMiniObject<{
+        coordinates: z.ZodMiniOptional<z.ZodMiniObject<{
+            latitude: z.ZodMiniNumber<number>;
+            longitude: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>;
+        city: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        postalCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        region: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        regionCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        countryCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        continent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        timezone: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    page: z.ZodMiniOptional<z.ZodMiniObject<{
+        path: z.ZodMiniString<string>;
+        query: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+        referrer: z.ZodMiniString<string>;
+        search: z.ZodMiniString<string>;
+        title: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        url: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    screen: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    userAgent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    traits: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniJSONSchema>>;
+    userId: z.ZodMiniString<string>;
+}, z.core.$strip>;
+/**
+ * Arguments for constructing identify events.
+ *
+ * @public
+ * @remarks
+ * Traits are merged by the API; only specified properties may be overwritten.
+ */
+export type IdentifyBuilderArgs = z.infer<typeof IdentifyBuilderArgs>;
+declare const PageViewBuilderArgs: z.ZodMiniObject<{
+    campaign: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        source: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        medium: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        term: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        content: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    locale: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    location: z.ZodMiniOptional<z.ZodMiniObject<{
+        coordinates: z.ZodMiniOptional<z.ZodMiniObject<{
+            latitude: z.ZodMiniNumber<number>;
+            longitude: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>;
+        city: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        postalCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        region: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        regionCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        countryCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        continent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        timezone: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    page: z.ZodMiniOptional<z.ZodMiniObject<{
+        path: z.ZodMiniString<string>;
+        query: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+        referrer: z.ZodMiniString<string>;
+        search: z.ZodMiniString<string>;
+        title: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        url: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    screen: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    userAgent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    properties: z.ZodMiniOptional<z.ZodMiniObject<{
+        path: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        query: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>>;
+        referrer: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        search: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        title: z.ZodMiniOptional<z.ZodMiniOptional<z.ZodMiniString<string>>>;
+        url: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+}, z.core.$strip>;
+/**
+ * Arguments for constructing page view events.
+ *
+ * @public
+ * @remarks
+ * Any properties passed here are merged with the base page properties from
+ * {@link EventBuilderConfig.getPageProperties}.
+ */
+export type PageViewBuilderArgs = z.infer<typeof PageViewBuilderArgs>;
+declare const ScreenViewBuilderArgs: z.ZodMiniObject<{
+    campaign: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        source: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        medium: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        term: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        content: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    locale: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    location: z.ZodMiniOptional<z.ZodMiniObject<{
+        coordinates: z.ZodMiniOptional<z.ZodMiniObject<{
+            latitude: z.ZodMiniNumber<number>;
+            longitude: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>;
+        city: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        postalCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        region: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        regionCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        countryCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        continent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        timezone: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    page: z.ZodMiniOptional<z.ZodMiniObject<{
+        path: z.ZodMiniString<string>;
+        query: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+        referrer: z.ZodMiniString<string>;
+        search: z.ZodMiniString<string>;
+        title: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        url: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    screen: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    userAgent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    name: z.ZodMiniString<string>;
+    properties: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniJSONSchema>;
+}, z.core.$strip>;
+/**
+ * Arguments for constructing screen view events.
+ *
+ * @public
+ * @remarks
+ * Any properties passed here are merged with the base screen properties from
+ * {@link EventBuilderConfig.getScreenProperties}.
+ */
+export type ScreenViewBuilderArgs = z.infer<typeof ScreenViewBuilderArgs>;
+declare const TrackBuilderArgs: z.ZodMiniObject<{
+    campaign: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        source: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        medium: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        term: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        content: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    locale: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    location: z.ZodMiniOptional<z.ZodMiniObject<{
+        coordinates: z.ZodMiniOptional<z.ZodMiniObject<{
+            latitude: z.ZodMiniNumber<number>;
+            longitude: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>;
+        city: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        postalCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        region: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        regionCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        countryCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        continent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        timezone: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    page: z.ZodMiniOptional<z.ZodMiniObject<{
+        path: z.ZodMiniString<string>;
+        query: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+        referrer: z.ZodMiniString<string>;
+        search: z.ZodMiniString<string>;
+        title: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        url: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    screen: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    userAgent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    event: z.ZodMiniString<string>;
+    properties: z.ZodMiniOptional<z.ZodMiniPrefault<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniJSONSchema>>>;
+}, z.core.$strip>;
+/**
+ * Arguments for constructing track events.
+ *
+ * @public
+ */
+export type TrackBuilderArgs = z.infer<typeof TrackBuilderArgs>;
+/**
+ * Default page properties used when no explicit page information is available.
+ *
+ * @public
+ *
+ * @defaultValue
+ * ```ts
+ * {
+ *   path: '',
+ *   query: {},
+ *   referrer: '',
+ *   search: '',
+ *   title: '',
+ *   url: '',
+ * }
+ * ```
+ *
+ * @remarks
+ * Values are required by the API; values may not be `undefined`. Empty values are valid.
+ */
+export declare const DEFAULT_PAGE_PROPERTIES: {
+    path: string;
+    query: {};
+    referrer: string;
+    search: string;
+    title: string;
+    url: string;
+};
+/**
+ * Internal helper class for building analytics and personalization events.
+ *
+ * @remarks
+ * This class coordinates configuration and argument validation to produce
+ * strongly-typed event payloads compatible with
+ * `@contentful/optimization-api-schemas`.
+ *
+ * @public
+ */
+declare class EventBuilder {
+    /**
+     * Application metadata attached to each event.
+     *
+     * @internal
+     */
+    app?: App;
+    /**
+     * Channel value attached to each event.
+     *
+     * @internal
+     */
+    channel: Channel;
+    /**
+     * Library metadata attached to each event.
+     *
+     * @internal
+     */
+    library: Library;
+    /**
+     * Function that provides the locale when available.
+     *
+     * @internal
+     */
+    getLocale: () => string | undefined;
+    /**
+     * Function that provides baseline page properties.
+     *
+     * @internal
+     */
+    getPageProperties: () => Page;
+    /**
+     * Function that provides the user agent string when available.
+     *
+     * @internal
+     */
+    getUserAgent: () => string | undefined;
+    /**
+     * Creates a new {@link EventBuilder} instance.
+     *
+     * @param config - Configuration used to customize event payloads.
+     *
+     * @internal
+     * @remarks
+     * Callers are expected to reuse a single instance when possible to avoid
+     * repeatedly reconfiguring the builder.
+     *
+     * @example
+     * ```ts
+     * const builder = new EventBuilder({
+     *   channel: 'web',
+     *   library: { name: '@contentful/optimization-sdk', version: '1.0.0' },
+     * })
+     * ```
+     */
+    constructor(config: EventBuilderConfig);
+    /**
+     * Builds the universal event properties shared across all event types.
+     *
+     * @param args - Arguments overriding the default context values.
+     * @returns A fully populated {@link UniversalEventProperties} object.
+     *
+     * @protected
+     *
+     * @remarks
+     * This method is used internally by the specific event-builder methods
+     * (e.g. {@link EventBuilder.buildPageView}).
+     */
+    protected buildUniversalEventProperties({ campaign, locale, location, page, screen, userAgent, }: UniversalEventBuilderArgs): UniversalEventProperties;
+    /**
+     * Builds a component view event payload for a Contentful entry-based component.
+     *
+     * @param args - {@link ComponentViewBuilderArgs} arguments describing the component view.
+     * @returns A {@link ComponentViewEvent} describing the view.
+     *
+     * @public
+     *
+     * @example
+     * ```ts
+     * const event = builder.buildComponentView({
+     *   componentId: 'entry-123',
+     *   experienceId: 'personalization-123',
+     *   variantIndex: 1,
+     * })
+     * ```
+     */
+    buildComponentView(args: ComponentViewBuilderArgs): ComponentViewEvent;
+    /**
+     * Builds a component view event payload for a Custom Flag component.
+     *
+     * @param args - {@link ComponentViewBuilderArgs} arguments describing the Custom Flag view.
+     * @returns A {@link ComponentViewEvent} describing the view.
+     *
+     * @public
+     *
+     * @remarks
+     * This is a specialized variant of {@link EventBuilder.buildComponentView}
+     * that sets `componentType` to `'Variable'`.
+     *
+     * @example
+     * ```ts
+     * const event = builder.buildFlagView({
+     *   componentId: 'feature-flag-key',
+     *   experienceId: 'personalization-123',
+     * })
+     * ```
+     */
+    buildFlagView(args: ComponentViewBuilderArgs): ComponentViewEvent;
+    /**
+     * Builds an identify event payload to associate a user ID with traits.
+     *
+     * @param args - {@link IdentifyBuilderArgs} arguments describing the identified user.
+     * @returns An {@link IdentifyEvent} payload.
+     *
+     * @public
+     *
+     * @remarks
+     * - Traits are merged by the API; only specified properties may be overwritten.
+     * - The User ID is consumer-specified and should not contain the value of any
+     *   ID generated by the Experience API.
+     *
+     * @example
+     * ```ts
+     * const event = builder.buildIdentify({
+     *   userId: 'user-123',
+     *   traits: { plan: 'pro' },
+     * })
+     * ```
+     */
+    buildIdentify(args: IdentifyBuilderArgs): IdentifyEvent;
+    /**
+     * Builds a page view event payload.
+     *
+     * @param args - Optional {@link PageViewBuilderArgs} overrides for the page view event.
+     * @returns A {@link PageViewEvent} payload.
+     *
+     * @public
+     *
+     * @remarks
+     * Page properties are created by merging:
+     * 1. The base page properties from {@link EventBuilderConfig.getPageProperties}, and
+     * 2. The partial `properties` argument passed in.
+     *
+     * The title always falls back to {@link DEFAULT_PAGE_PROPERTIES}.title when undefined.
+     *
+     * @example
+     * ```ts
+     * const event = builder.buildPageView({
+     *   properties: {
+     *     title: 'Homepage',
+     *   },
+     * })
+     * ```
+     */
+    buildPageView(args?: PageViewBuilderArgs): PageViewEvent;
+    /**
+     * Builds a screen view event payload.
+     *
+     * @param args - {@link ScreenViewBuilderArgs} arguments for the screen view event.
+     * @returns A {@link ScreenViewEvent} payload.
+     *
+     * @public
+     *
+     * @example
+     * ```ts
+     * const event = builder.buildScreenView({
+     *   name: 'home',
+     *   properties: {
+     *     title: 'Home Screen',
+     *   },
+     * })
+     * ```
+     */
+    buildScreenView(args: ScreenViewBuilderArgs): ScreenViewEvent;
+    /**
+     * Builds a track event payload for arbitrary user actions.
+     *
+     * @param args - {@link TrackBuilderArgs} arguments describing the tracked event.
+     * @returns A {@link TrackEvent} payload.
+     *
+     * @public
+     *
+     * @example
+     * ```ts
+     * const event = builder.buildTrack({
+     *   event: 'button_clicked',
+     *   properties: { id: 'primary-cta', location: 'hero' },
+     * })
+     * ```
+     */
+    buildTrack(args: TrackBuilderArgs): TrackEvent;
+}
+export default EventBuilder;
+//# sourceMappingURL=EventBuilder.d.ts.map

package/dist/builders/EventBuilder.d.ts.map

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