@contentful/optimization-api-client 0.1.0-alpha8 → 0.1.0-alpha9

package/dist/index.d.ts

@@ -1,8 +1,1649 @@
-export { default as ApiClient } from './ApiClient';
-export * from '@contentful/optimization-api-schemas';
-export * from './ApiClient';
-export * from './ApiClientBase';
-export * from './builders';
-export * from './experience';
-export * from './insights';
-//# sourceMappingURL=index.d.ts.map
+/**
+ * @packageDocumentation
+ *
+ * The Contentful Optimization API Client Library provides methods for
+ * interfacing with Contentful's Experience and Insights APIs, which serve its
+ * Personalization and Analytics products.
+ */
+
+import { App } from '@contentful/optimization-api-schemas';
+import { BatchExperienceEventArray } from '@contentful/optimization-api-schemas';
+import { BatchExperienceResponseData } from '@contentful/optimization-api-schemas';
+import { BatchInsightsEventArray } from '@contentful/optimization-api-schemas';
+import { Channel } from '@contentful/optimization-api-schemas';
+import { ComponentClickEvent } from '@contentful/optimization-api-schemas';
+import { ComponentHoverEvent } from '@contentful/optimization-api-schemas';
+import { ComponentViewEvent } from '@contentful/optimization-api-schemas';
+import { ExperienceEventArray } from '@contentful/optimization-api-schemas';
+import { IdentifyEvent } from '@contentful/optimization-api-schemas';
+import { Library } from '@contentful/optimization-api-schemas';
+import { OptimizationData } from '@contentful/optimization-api-schemas';
+import { Page } from '@contentful/optimization-api-schemas';
+import { PageViewEvent } from '@contentful/optimization-api-schemas';
+import { ScreenViewEvent } from '@contentful/optimization-api-schemas';
+import { TrackEvent as TrackEvent_2 } from '@contentful/optimization-api-schemas';
+import { UniversalEventProperties } from '@contentful/optimization-api-schemas';
+import * as z from 'zod/mini';
+
+/**
+ * Aggregated API client providing access to Experience and Insights APIs.
+ *
+ * @remarks
+ * This client encapsulates shared configuration and exposes dedicated
+ * sub-clients for personalization and analytics use cases.
+ *
+ * @example
+ * ```ts
+ * const client = new ApiClient({
+ *   clientId: 'org-id',
+ *   environment: 'main',
+ *   personalization: {
+ *     // experience-specific overrides
+ *   },
+ *   analytics: {
+ *     // insights-specific overrides
+ *   },
+ * })
+ *
+ * const profile = await client.experience.getProfile('profile-id')
+ * await client.insights.sendBatchEvents(batches)
+ * ```
+ *
+ * @see {@link ExperienceApiClient}
+ * @see {@link InsightsApiClient}
+ *
+ * @public
+ */
+export declare class ApiClient {
+    /**
+     * Shared configuration applied to both Experience and Insights clients.
+     *
+     * @see {@link ApiConfig}
+     */
+    readonly config: ApiConfig;
+    /**
+     * Client for personalization and experience-related operations.
+     *
+     * @see {@link ExperienceApiClient}
+     */
+    readonly experience: ExperienceApiClient;
+    /**
+     * Client for analytics and insights-related operations.
+     *
+     * @see {@link InsightsApiClient}
+     */
+    readonly insights: InsightsApiClient;
+    /**
+     * Creates a new aggregated {@link ApiClient} instance.
+     *
+     * @param config - Global API client configuration with optional per-client overrides.
+     */
+    constructor(config: ApiClientConfig);
+}
+
+/**
+ * Base class for API clients that provides shared configuration and error logging.
+ *
+ * @remarks
+ * This abstract class is intended for internal use within the package and
+ * should not be treated as part of the public API surface.
+ *
+ * Concrete API clients should extend this class to inherit consistent logging
+ * behavior and fetch configuration.
+ *
+ * @example
+ * ```ts
+ * interface MyClientConfig extends ApiConfig {
+ *   // additional config
+ * }
+ *
+ * class MyClient extends ApiClientBase {
+ *   constructor(config: MyClientConfig) {
+ *     super('MyClient', config)
+ *   }
+ *
+ *   async getSomething() {
+ *     const response = await this.fetch('https://example.com', { method: 'GET' })
+ *     return response.json()
+ *   }
+ * }
+ * ```
+ *
+ * @internal
+ */
+declare abstract class ApiClientBase {
+    /**
+     * Name of the API client, used in log messages and as the `apiName` for fetch.
+     */
+    protected readonly name: string;
+    /**
+     * Client identifier used for authentication or tracking.
+     */
+    protected readonly clientId: string;
+    /**
+     * Contentful environment associated with this client.
+     */
+    protected readonly environment: string;
+    /**
+     * Protected fetch method used by the client to perform HTTP requests.
+     */
+    protected readonly fetch: FetchMethod;
+    /**
+     * Creates a new API client base instance.
+     *
+     * @param name - Human-readable name of the client (used for logging and `apiName`).
+     * @param config - Configuration options for the client.
+     */
+    constructor(name: string, { fetchOptions, clientId, environment }: ApiConfig);
+    /**
+     * Logs errors that occur during API requests with standardized messages.
+     *
+     * @param error - The error thrown by the underlying operation.
+     * @param options - Additional metadata about the request.
+     * @param options.requestName - Human-readable name of the request operation.
+     *
+     * @remarks
+     * Abort errors are logged at `warn` level and other errors at `error` level.
+     * The log message includes the client name for better debugging context.
+     */
+    protected logRequestError(error: unknown, { requestName }: {
+        requestName: string;
+    }): void;
+}
+
+/**
+ * Configuration for the high-level {@link ApiClient}.
+ *
+ * @public
+ */
+export declare interface ApiClientConfig extends Pick<ApiConfig, GlobalApiConfigProperties> {
+    /**
+     * Configuration for the personalization (Experience) API client.
+     *
+     * @remarks
+     * Shared fields (`clientId`, `environment`, `fetchOptions`) are inherited
+     * from top-level config; this object is for Experience-specific options.
+     */
+    personalization?: Omit<ExperienceApiClientConfig, GlobalApiConfigProperties>;
+    /**
+     * Configuration for the analytics (Insights) API client.
+     *
+     * @remarks
+     * Shared fields (`clientId`, `environment`, `fetchOptions`) are inherited
+     * from top-level config; this object is for Insights-specific options.
+     */
+    analytics?: Omit<InsightsApiClientConfig, GlobalApiConfigProperties>;
+}
+
+/**
+ * Configuration options for API clients extending {@link ApiClientBase}.
+ *
+ * @public
+ */
+export declare interface ApiConfig {
+    /**
+     * Base URL for the API.
+     *
+     * @remarks
+     * When omitted, the concrete client is expected to construct full URLs
+     * internally.
+     */
+    baseUrl?: string;
+    /**
+     * Contentful environment identifier.
+     *
+     * @defaultValue `'main'`
+     */
+    environment?: string;
+    /**
+     * Options used to configure the underlying protected fetch method.
+     *
+     * @remarks
+     * `apiName` is derived from the client name and must not be provided here.
+     */
+    fetchOptions?: Omit<ProtectedFetchMethodOptions, 'apiName'>;
+    /**
+     * Client identifier used for authentication or tracking.
+     */
+    clientId: string;
+}
+
+/**
+ * Base options shared across fetch method factories.
+ *
+ * @public
+ */
+declare interface BaseFetchMethodOptions {
+    /**
+     * Human-readable name of the API being called.
+     *
+     * @remarks
+     * Used primarily for logging and error messages.
+     */
+    apiName?: string;
+    /**
+     * Custom fetch implementation to use instead of the global `fetch`.
+     *
+     * @remarks
+     * This is useful for providing polyfills, mocks, or instrumented fetch
+     * implementations.
+     */
+    fetchMethod?: FetchMethod;
+}
+
+/**
+ * Parameters used when performing a batch profile update.
+ *
+ * @internal
+ */
+declare interface BatchUpdateProfileParams {
+    /**
+     * Batch of events to process.
+     */
+    events: BatchExperienceEventArray;
+}
+
+/**
+ * Arguments for constructing component click events.
+ *
+ * @public
+ */
+export declare type ComponentClickBuilderArgs = z.infer<typeof ComponentClickBuilderArgs_2>;
+
+declare const ComponentClickBuilderArgs_2: 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>>;
+}, z.core.$strip>;
+
+/**
+ * Arguments for constructing component click events.
+ *
+ * @public
+ */
+declare type ComponentClickBuilderArgs = z.infer<typeof ComponentClickBuilderArgs_2>;
+
+/**
+ * Arguments for constructing component hover events.
+ *
+ * @public
+ */
+export declare type ComponentHoverBuilderArgs = z.infer<typeof ComponentHoverBuilderArgs_2>;
+
+declare const ComponentHoverBuilderArgs_2: 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>>;
+    componentHoverId: z.ZodMiniString<string>;
+    hoverDurationMs: z.ZodMiniNumber<number>;
+}, z.core.$strip>;
+
+/**
+ * Arguments for constructing component hover events.
+ *
+ * @public
+ */
+declare type ComponentHoverBuilderArgs = z.infer<typeof ComponentHoverBuilderArgs_2>;
+
+/**
+ * Arguments shared by component view, click, and hover events.
+ *
+ * @public
+ */
+export declare type ComponentInteractionBuilderArgsBase = z.infer<typeof ComponentInteractionBuilderArgsBase_2>;
+
+declare const ComponentInteractionBuilderArgsBase_2: 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>>;
+}, z.core.$strip>;
+
+/**
+ * Arguments shared by component view, click, and hover events.
+ *
+ * @public
+ */
+declare type ComponentInteractionBuilderArgsBase = z.infer<typeof ComponentInteractionBuilderArgsBase_2>;
+
+/**
+ * Arguments for constructing component view events.
+ *
+ * @public
+ */
+export declare type ComponentViewBuilderArgs = z.infer<typeof ComponentViewBuilderArgs_2>;
+
+declare const ComponentViewBuilderArgs_2: 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>>;
+    componentViewId: z.ZodMiniString<string>;
+    viewDurationMs: z.ZodMiniNumber<number>;
+}, z.core.$strip>;
+
+/**
+ * Arguments for constructing component view events.
+ *
+ * @public
+ */
+declare type ComponentViewBuilderArgs = z.infer<typeof ComponentViewBuilderArgs_2>;
+
+/**
+ * Parameters used when creating a profile.
+ *
+ * @internal
+ */
+declare interface CreateProfileParams {
+    /**
+     * Events used to aggregate the profile state.
+     */
+    events: ExperienceEventArray;
+}
+
+/**
+ * Default page properties used when no explicit page information is available.
+ *
+ * @defaultValue
+ * ```ts
+ * {
+ *   path: '',
+ *   query: {},
+ *   referrer: '',
+ *   search: '',
+ *   title: '',
+ *   url: '',
+ * }
+ * ```
+ *
+ * @remarks
+ * Values are required by the API; values may not be `undefined`. Empty values are valid.
+ *
+ * @public
+ */
+export declare const DEFAULT_PAGE_PROPERTIES: {
+    path: string;
+    query: {};
+    referrer: string;
+    search: string;
+    title: string;
+    url: string;
+};
+
+/**
+ * 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`.
+ *
+ * @see {@link EventBuilderConfig}
+ *
+ * @public
+ */
+export 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.
+     *
+     * @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.
+     *
+     * @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;
+    private buildEntryComponentBase;
+    /**
+     * 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.
+     *
+     * @example
+     * ```ts
+     * const event = builder.buildComponentView({
+     *   componentId: 'entry-123',
+     *   componentViewId: crypto.randomUUID(),
+     *   experienceId: 'personalization-123',
+     *   variantIndex: 1,
+     *   viewDurationMs: 1_000,
+     * })
+     * ```
+     *
+     * @public
+     */
+    buildComponentView(args: ComponentViewBuilderArgs): ComponentViewEvent;
+    /**
+     * Builds a component click event payload for a Contentful entry-based component.
+     *
+     * @param args - {@link ComponentClickBuilderArgs} arguments describing the component click.
+     * @returns A {@link ComponentClickEvent} describing the click.
+     *
+     * @example
+     * ```ts
+     * const event = builder.buildComponentClick({
+     *   componentId: 'entry-123',
+     *   experienceId: 'personalization-123',
+     *   variantIndex: 1,
+     * })
+     * ```
+     *
+     * @public
+     */
+    buildComponentClick(args: ComponentClickBuilderArgs): ComponentClickEvent;
+    /**
+     * Builds a component hover event payload for a Contentful entry-based component.
+     *
+     * @param args - {@link ComponentHoverBuilderArgs} arguments describing the component hover.
+     * @returns A {@link ComponentHoverEvent} describing the hover.
+     *
+     * @example
+     * ```ts
+     * const event = builder.buildComponentHover({
+     *   componentId: 'entry-123',
+     *   componentHoverId: crypto.randomUUID(),
+     *   experienceId: 'personalization-123',
+     *   hoverDurationMs: 1_000,
+     *   variantIndex: 1,
+     * })
+     * ```
+     *
+     * @public
+     */
+    buildComponentHover(args: ComponentHoverBuilderArgs): ComponentHoverEvent;
+    /**
+     * 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.
+     *
+     * @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',
+     *   componentViewId: crypto.randomUUID(),
+     *   experienceId: 'personalization-123',
+     *   viewDurationMs: 1_000,
+     * })
+     * ```
+     *
+     * @public
+     */
+    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.
+     *
+     * @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' },
+     * })
+     * ```
+     *
+     * @public
+     */
+    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.
+     *
+     * @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',
+     *   },
+     * })
+     * ```
+     *
+     * @public
+     */
+    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.
+     *
+     * @example
+     * ```ts
+     * const event = builder.buildScreenView({
+     *   name: 'home',
+     *   properties: {
+     *     title: 'Home Screen',
+     *   },
+     * })
+     * ```
+     *
+     * @public
+     */
+    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.
+     *
+     * @example
+     * ```ts
+     * const event = builder.buildTrack({
+     *   event: 'button_clicked',
+     *   properties: { id: 'primary-cta', location: 'hero' },
+     * })
+     * ```
+     *
+     * @public
+     */
+    buildTrack(args: TrackBuilderArgs): TrackEvent_2;
+}
+
+/**
+ * Configuration options for creating an {@link EventBuilder} instance.
+ *
+ * @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,
+ *   }),
+ * })
+ * ```
+ *
+ * @public
+ */
+export declare 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;
+}
+
+/**
+ * Default base URL for the Experience API.
+ *
+ * @public
+ */
+export declare const EXPERIENCE_BASE_URL = "https://experience.ninetailed.co/";
+
+/**
+ * Client for interacting with the Experience API.
+ *
+ * @remarks
+ * This client is responsible for reading and mutating Ninetailed profiles
+ * using the Experience API.
+ *
+ * @example
+ * ```ts
+ * const client = new ExperienceApiClient({
+ *   clientId: 'org-id',
+ *   environment: 'main',
+ * })
+ *
+ * const profile = await client.getProfile('profile-id')
+ * ```
+ *
+ * @see {@link ApiClientBase}
+ *
+ * @public
+ */
+declare class ExperienceApiClient extends ApiClientBase {
+    /**
+     * Base URL used for Experience API requests.
+     */
+    protected readonly baseUrl: string;
+    private readonly enabledFeatures?;
+    private readonly ip?;
+    private readonly locale?;
+    private readonly plainText?;
+    private readonly preflight?;
+    /**
+     * Creates a new {@link ExperienceApiClient} instance.
+     *
+     * @param config - Configuration for the Experience API client.
+     */
+    constructor(config: ExperienceApiClientConfig);
+    /**
+     * Retrieves a profile by ID.
+     *
+     * @param id - The profile ID to retrieve.
+     * @param options - Optional request options. `preflight` and `plainText` are not allowed here.
+     * @returns The current optimization data for the profile.
+     *
+     * @throws {@link Error}
+         * Thrown if `id` is missing or the underlying request fails.
+         *
+         * @example
+         * ```ts
+         * const profile = await client.getProfile('profile-id', {
+         *   locale: 'en-US',
+         * })
+         * ```
+         */
+     getProfile(id: string, options?: Omit<RequestOptions, 'preflight' | 'plainText'>): Promise<OptimizationData>;
+     /**
+      * Sends a POST request to mutate a profile or profiles.
+      *
+      * @param request - Mutation request options including URL, body, and request options.
+      * @returns The raw {@link Response} from the underlying fetch.
+      *
+      * @internal
+      */
+     private makeProfileMutationRequest;
+     /**
+      * Creates a profile and returns the resulting optimization data.
+      *
+      * @param params - Parameters containing the events to aggregate into the profile.
+      * @param options - Optional request options.
+      * @returns The optimization data for the newly created profile.
+      *
+      * @remarks
+      * The returned profile ID can be used for subsequent update requests.
+      *
+      * @example
+      * ```ts
+      * const data = await client.createProfile({
+      *   events: [{ type: 'identify', userId: 'user-123' }],
+      * })
+      * ```
+      */
+     createProfile({ events }: CreateProfileParams, options?: RequestOptions): Promise<OptimizationData>;
+     /**
+      * Updates an existing profile with the given profile ID.
+      *
+      * @param params - Parameters including the profile ID and events.
+      * @param options - Optional request options.
+      * @returns The updated optimization data for the profile.
+      *
+      * @throws {@link Error}
+          * Thrown if `profileId` is missing or the underlying request fails.
+          *
+          * @example
+          * ```ts
+          * const data = await client.updateProfile({
+          *   profileId: 'profile-id',
+          *   events: [{ type: 'track', event: 'viewed_video' }],
+          * })
+          * ```
+          */
+      updateProfile({ profileId, events }: UpdateProfileParams, options?: RequestOptions): Promise<OptimizationData>;
+      /**
+       * Creates or updates a profile depending on whether a `profileId` is provided.
+       *
+       * @param params - Parameters including optional profile ID and events.
+       * @param options - Optional request options.
+       * @returns The resulting optimization data.
+       *
+       * @example
+       * ```ts
+       * // Create
+       * await client.upsertProfile({ events })
+       *
+       * // Update
+       * await client.upsertProfile({ profileId: 'profile-id', events })
+       * ```
+       */
+      upsertProfile({ profileId, events }: UpsertProfileParams, options?: RequestOptions): Promise<OptimizationData>;
+      /**
+       * Sends multiple events to the Ninetailed Experience API to upsert many profiles.
+       *
+       * @param params - Parameters containing the batch of events.
+       * @param options - Optional request options.
+       * @returns The list of profiles affected by the batch operation.
+       *
+       * @remarks
+       * Batch requests must contain at least one event. Every event must contain
+       * an anonymous ID. Profiles will be created or updated according to the
+       * anonymous ID.
+       *
+       * This method is intended to be used from server environments.
+       *
+       * @example
+       * ```ts
+       * const profiles = await client.upsertManyProfiles({
+       *   events: [
+       *     { anonymousId: 'anon-1', type: 'identify', ... },
+       *     { anonymousId: 'anon-2', type: 'identify', ... },
+       *   ],
+       * })
+       * ```
+       */
+      upsertManyProfiles({ events }: BatchUpdateProfileParams, options?: RequestOptions): Promise<BatchExperienceResponseData['profiles']>;
+      /**
+       * Constructs a request URL with query parameters derived from request options.
+       *
+       * @param path - Path relative to the Experience API base URL.
+       * @param options - Request options that may influence query parameters.
+       * @returns The fully constructed URL as a string.
+       *
+       * @internal
+       */
+      private constructUrl;
+      /**
+       * Constructs request headers based on request options and default configuration.
+       *
+       * @param options - Request options that may influence headers.
+       * @returns A record of HTTP headers to send with the request.
+       *
+       * @internal
+       */
+      private constructHeaders;
+      /**
+       * Constructs the `options` section of the request body for profile mutations.
+       *
+       * @param options - Request options that may specify enabled features.
+       * @returns Experience API body options including feature flags.
+       *
+       * @internal
+       */
+      private readonly constructBodyOptions;
+      /**
+       * Construct and validate the singular Experience mutation request payload.
+       *
+       * @param events - Events that should be evaluated by the Experience API.
+       * @param options - Request options that may contribute body options.
+       * @returns Validated singular Experience request body.
+       *
+       * @internal
+       */
+      private constructExperienceRequestBody;
+     }
+
+     /**
+      * Configuration for {@link ExperienceApiClient}.
+      *
+      * @public
+      */
+     export declare interface ExperienceApiClientConfig extends ApiConfig, RequestOptions {
+     }
+
+     /**
+      * Feature flags supported by the Experience API.
+      *
+      * @internal
+      */
+     declare type Feature = 'ip-enrichment' | 'location';
+
+     /**
+      * Signature of a fetch method used by the API clients.
+      *
+      * @param url - The request URL.
+      * @param init - Initialization options passed to `fetch`.
+      * @returns A promise that resolves with the {@link Response}.
+      *
+      * @remarks
+      * This abstraction allows the underlying implementation to be replaced,
+      * for example in tests or different runtime environments.
+      *
+      * @example
+      * ```ts
+      * const method: FetchMethod = async (url, init) => {
+      *   return fetch(url, init)
+      * }
+      * ```
+      *
+      * @public
+      */
+     declare type FetchMethod = (url: string | URL, init: RequestInit) => Promise<Response>;
+
+     /**
+      * Options passed to callback functions invoked by fetch wrappers.
+      *
+      * @remarks
+      * Not all fields are guaranteed to be present in all callback scenarios.
+      *
+      * @public
+      */
+     declare interface FetchMethodCallbackOptions {
+         /**
+          * Name of the API associated with the request.
+          */
+         apiName?: string;
+         /**
+          * Error that caused the callback to be invoked, if available.
+          */
+         error?: Error;
+         /**
+          * The current attempt number (for retry callbacks).
+          */
+         attemptNumber?: number;
+         /**
+          * Number of retry attempts remaining (for retry callbacks).
+          */
+         retriesLeft?: number;
+     }
+
+     /**
+      * Properties that may be shared between global and per-client API configuration.
+      *
+      * @public
+      */
+     export declare type GlobalApiConfigProperties = 'environment' | 'fetchOptions' | 'clientId';
+
+     /**
+      * Arguments for constructing identify events.
+      *
+      * @remarks
+      * Traits are merged by the API; only specified properties may be overwritten.
+      *
+      * @public
+      */
+     export declare type IdentifyBuilderArgs = z.infer<typeof IdentifyBuilderArgs_2>;
+
+     declare const IdentifyBuilderArgs_2: 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.
+      *
+      * @remarks
+      * Traits are merged by the API; only specified properties may be overwritten.
+      *
+      * @public
+      */
+     declare type IdentifyBuilderArgs = z.infer<typeof IdentifyBuilderArgs_2>;
+
+     /**
+      * Default base URL for the Insights ingest API.
+      *
+      * @public
+      */
+     export declare const INSIGHTS_BASE_URL = "https://ingest.insights.ninetailed.co/";
+
+     /**
+      * Client for sending analytics and insights events to the Ninetailed Insights API.
+      *
+      * @remarks
+      * This client is optimized for sending batched events, optionally using a
+      * custom beacon-like handler when available.
+      *
+      * @example
+      * ```ts
+      * const insightsClient = new InsightsApiClient({
+      *   clientId: 'org-id',
+      *   environment: 'main',
+      * })
+      *
+      * await insightsClient.sendBatchEvents([
+      *   {
+      *     profile: { id: 'profile-123', ... },
+      *     events: [
+      *       {
+      *         type: 'track',
+      *         event: 'button_clicked',
+      *         properties: { id: 'primary-cta' },
+      *       },
+      *     ],
+      *   }
+      * ])
+      * ```
+      *
+      * @see {@link ApiClientBase}
+      *
+      * @public
+      */
+     declare class InsightsApiClient extends ApiClientBase {
+         /**
+          * Base URL used for Insights API requests.
+          */
+         protected readonly baseUrl: string;
+         /**
+          * Optional handler used to enqueue events via the Beacon API or a similar mechanism.
+          */
+         private readonly beaconHandler;
+         /**
+          * Creates a new {@link InsightsApiClient} instance.
+          *
+          * @param config - Configuration for the Insights API client.
+          *
+          * @example
+          * ```ts
+          * const client = new InsightsApiClient({
+          *   clientId: 'org-id',
+          *   environment: 'main',
+          *   beaconHandler: (url, data) => {
+          *     return navigator.sendBeacon(url.toString(), JSON.stringify(data))
+          *   },
+          * })
+          * ```
+          */
+         constructor(config: InsightsApiClientConfig);
+         /**
+          * Sends batches of insights events to the Ninetailed Insights API.
+          *
+          * @param batches - Array of event batches to send.
+          * @param options - Optional request options, including a per-call `beaconHandler`.
+          * @returns `true` when the event batch is successfully queued by the beacon
+          * handler or a direct request is successfully sent, `false` otherwise.
+          *
+          * @remarks
+          * If a `beaconHandler` is provided (either in the method call or in the
+          * client configuration) it will be invoked first. When the handler returns
+          * `true`, the events are considered successfully queued and no network
+          * request is made by this method.
+          *
+          * If the handler is missing or returns `false`, the events are emitted
+          * immediately via `fetch`.
+          *
+          * @example
+          * ```ts
+          * const success = await insightsClient.sendBatchEvents(batches)
+          * ```
+          *
+          * @example
+          * ```ts
+          * // Override beaconHandler for a single call
+          * const success = await insightsClient.sendBatchEvents(batches, {
+          *   beaconHandler: (url, data) => {
+          *     return navigator.sendBeacon(url.toString(), JSON.stringify(data))
+          *   },
+          * })
+          * ```
+          */
+         sendBatchEvents(batches: BatchInsightsEventArray, options?: RequestOptions_2): Promise<boolean>;
+     }
+
+     /**
+      * Configuration for {@link InsightsApiClient}.
+      *
+      * @public
+      */
+     export declare interface InsightsApiClientConfig extends ApiConfig, RequestOptions_2 {
+     }
+
+     /**
+      * Arguments for constructing page view events.
+      *
+      * @remarks
+      * Any properties passed here are merged with the base page properties from
+      * {@link EventBuilderConfig.getPageProperties}.
+      *
+      * @public
+      */
+     export declare type PageViewBuilderArgs = z.infer<typeof PageViewBuilderArgs_2>;
+
+     declare const PageViewBuilderArgs_2: 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.
+      *
+      * @remarks
+      * Any properties passed here are merged with the base page properties from
+      * {@link EventBuilderConfig.getPageProperties}.
+      *
+      * @public
+      */
+     declare type PageViewBuilderArgs = z.infer<typeof PageViewBuilderArgs_2>;
+
+     /**
+      * Options for {@link createProtectedFetchMethod}, combining timeout and retry behavior.
+      *
+      * @see {@link RetryFetchMethodOptions}
+      * @see {@link TimeoutFetchMethodOptions}
+      *
+      * @public
+      */
+     declare interface ProtectedFetchMethodOptions extends RetryFetchMethodOptions, TimeoutFetchMethodOptions {
+     }
+
+     /**
+      * Options that control how requests to the Experience API are handled.
+      *
+      * @internal
+      */
+     declare interface RequestOptions {
+         /**
+          * Enabled features (for example, `"ip-enrichment"`) which the API should use for this request.
+          *
+          * @remarks
+          * When omitted, a default set of features may be applied.
+          */
+         enabledFeatures?: Feature[];
+         /**
+          * IP address to override the API behavior for IP analysis.
+          *
+          * @remarks
+          * Commonly used in ESR or SSR environments, as the API would otherwise use
+          * the server IP.
+          */
+         ip?: string;
+         /**
+          * Locale used to translate `location.city` and `location.country`.
+          *
+          * @remarks
+          * When omitted, a server-side default may be used.
+          */
+         locale?: string;
+         /**
+          * When `true`, sends performance-critical endpoints in plain text.
+          *
+          * @remarks
+          * The Ninetailed API accepts certain endpoints in plain text to avoid CORS
+          * preflight requests, which can improve performance in browser environments.
+          */
+         plainText?: boolean;
+         /**
+          * When `true`, instructs the API to aggregate a new profile state but not store it.
+          *
+          * @remarks
+          * This is commonly used in ESR or SSR environments where you want to
+          * preview the result without persisting changes.
+          */
+         preflight?: boolean;
+     }
+
+     /**
+      * Options that control how Insights events are sent.
+      *
+      * @internal
+      */
+     declare interface RequestOptions_2 {
+         /**
+          * Handler used to enqueue events via the Beacon API or a similar mechanism.
+          *
+          * @param url - Target URL for the batched events.
+          * @param data - Array of batched insights events to be sent.
+          * @returns `true` if the events were successfully queued, `false` otherwise.
+          *
+          * @remarks
+          * When provided, this handler is preferred over direct `fetch` calls. If it
+          * returns `false`, the client falls back to emitting events immediately via
+          * `fetch`.
+          */
+         beaconHandler?: (url: string | URL, data: BatchInsightsEventArray) => boolean;
+     }
+
+     /**
+      * Configuration options for {@link createRetryFetchMethod}.
+      *
+      * @public
+      */
+     declare interface RetryFetchMethodOptions extends BaseFetchMethodOptions {
+         /**
+          * Delay (in milliseconds) between retry attempts.
+          *
+          * @defaultValue `0`
+          */
+         intervalTimeout?: number;
+         /**
+          * Callback invoked whenever a retry attempt fails.
+          *
+          * @param options - Information about the failed attempt.
+          *
+          * @remarks
+          * This callback is invoked with additional metadata such as the attempt
+          * number and the number of retries left.
+          */
+         onFailedAttempt?: (options: FetchMethodCallbackOptions) => void;
+         /**
+          * Maximum number of retry attempts.
+          *
+          * @defaultValue `1`
+          */
+         retries?: number;
+     }
+
+     /**
+      * Arguments for constructing screen view events.
+      *
+      * @remarks
+      * Any properties passed here are merged with the base screen properties from
+      * {@link EventBuilderConfig.getScreenProperties}.
+      *
+      * @public
+      */
+     export declare type ScreenViewBuilderArgs = z.infer<typeof ScreenViewBuilderArgs_2>;
+
+     declare const ScreenViewBuilderArgs_2: 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.
+      *
+      * @remarks
+      * Any properties passed here are merged with the base screen properties from
+      * {@link EventBuilderConfig.getScreenProperties}.
+      *
+      * @public
+      */
+     declare type ScreenViewBuilderArgs = z.infer<typeof ScreenViewBuilderArgs_2>;
+
+     /**
+      * Configuration options for {@link createTimeoutFetchMethod}.
+      *
+      * @public
+      */
+     declare interface TimeoutFetchMethodOptions extends BaseFetchMethodOptions {
+         /**
+          * Callback invoked when a request exceeds the configured timeout.
+          *
+          * @param options - Information about the timed-out request.
+          *
+          * @remarks
+          * If this callback is not provided, a default error is logged.
+          *
+          * @see {@link FetchMethodCallbackOptions}
+          */
+         onRequestTimeout?: (options: FetchMethodCallbackOptions) => void;
+         /**
+          * Maximum time (in milliseconds) to wait for a response before aborting the request.
+          *
+          * @defaultValue `3000`
+          */
+         requestTimeout?: number;
+     }
+
+     /**
+      * Arguments for constructing track events.
+      *
+      * @public
+      */
+     export declare type TrackBuilderArgs = z.infer<typeof TrackBuilderArgs_2>;
+
+     declare const TrackBuilderArgs_2: 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
+      */
+     declare type TrackBuilderArgs = z.infer<typeof TrackBuilderArgs_2>;
+
+     /**
+      * Arguments used to construct the universal (shared) portion of all events.
+      *
+      * @public
+      */
+     export declare type UniversalEventBuilderArgs = z.infer<typeof UniversalEventBuilderArgs_2>;
+
+     declare const UniversalEventBuilderArgs_2: 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
+      */
+     declare type UniversalEventBuilderArgs = z.infer<typeof UniversalEventBuilderArgs_2>;
+
+     /**
+      * Parameters used when updating an existing profile.
+      *
+      * @internal
+      */
+     declare interface UpdateProfileParams extends CreateProfileParams {
+         /**
+          * ID of the profile to update.
+          */
+         profileId: string;
+     }
+
+     /**
+      * Parameters used when creating or updating a profile.
+      *
+      * @internal
+      */
+     declare interface UpsertProfileParams extends CreateProfileParams {
+         /**
+          * Optional ID of the profile; when omitted, a new profile is created.
+          */
+         profileId?: string;
+     }
+
+     export { }