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

package/dist/index.d.cts

@@ -1,8 +1,18 @@
+/**
+ * @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 { BatchExperienceData } 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';
@@ -18,8 +28,6 @@ import * as z from 'zod/mini';
 /**
  * Aggregated API client providing access to Experience and Insights APIs.
  *
- * @public
- *
  * @remarks
  * This client encapsulates shared configuration and exposes dedicated
  * sub-clients for personalization and analytics use cases.
@@ -29,7 +37,6 @@ import * as z from 'zod/mini';
  * const client = new ApiClient({
  *   clientId: 'org-id',
  *   environment: 'main',
- *   preview: false,
  *   personalization: {
  *     // experience-specific overrides
  *   },
@@ -39,20 +46,31 @@ import * as z from 'zod/mini';
  * })
  *
  * const profile = await client.experience.getProfile('profile-id')
- * const batch = await client.insights.upsertManyProfiles({ events: batchEvents })
+ * 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;
     /**
@@ -66,8 +84,6 @@ export declare class ApiClient {
 /**
  * Base class for API clients that provides shared configuration and error logging.
  *
- * @internal
- *
  * @remarks
  * This abstract class is intended for internal use within the package and
  * should not be treated as part of the public API surface.
@@ -92,6 +108,8 @@ export declare class ApiClient {
  *   }
  * }
  * ```
+ *
+ * @internal
  */
 declare abstract class ApiClientBase {
     /**
@@ -124,8 +142,6 @@ declare abstract class ApiClientBase {
      * @param options - Additional metadata about the request.
      * @param options.requestName - Human-readable name of the request operation.
      *
-     * @protected
-     *
      * @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.
@@ -145,16 +161,16 @@ export declare interface ApiClientConfig extends Pick<ApiConfig, GlobalApiConfig
      * Configuration for the personalization (Experience) API client.
      *
      * @remarks
-     * Any properties shared with {@link ApiConfig} are taken from the top-level
-     * config and overridden by this object when specified.
+     * 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
-     * Any properties shared with {@link ApiConfig} are taken from the top-level
-     * config and overridden by this object when specified.
+     * Shared fields (`clientId`, `environment`, `fetchOptions`) are inherited
+     * from top-level config; this object is for Insights-specific options.
      */
     analytics?: Omit<InsightsApiClientConfig, GlobalApiConfigProperties>;
 }
@@ -176,8 +192,7 @@ export declare interface ApiConfig {
     /**
      * Contentful environment identifier.
      *
-     * @remarks
-     * Defaults to `main` when not provided.
+     * @defaultValue `'main'`
      */
     environment?: string;
     /**
@@ -218,6 +233,8 @@ declare interface BaseFetchMethodOptions {
 
 /**
  * Parameters used when performing a batch profile update.
+ *
+ * @internal
  */
 declare interface BatchUpdateProfileParams {
     /**
@@ -226,6 +243,170 @@ declare interface BatchUpdateProfileParams {
     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.
  *
@@ -272,6 +453,8 @@ declare const ComponentViewBuilderArgs_2: z.ZodMiniObject<{
     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>;
 
 /**
@@ -283,6 +466,8 @@ declare type ComponentViewBuilderArgs = z.infer<typeof ComponentViewBuilderArgs_
 
 /**
  * Parameters used when creating a profile.
+ *
+ * @internal
  */
 declare interface CreateProfileParams {
     /**
@@ -294,8 +479,6 @@ declare interface CreateProfileParams {
 /**
  * Default page properties used when no explicit page information is available.
  *
- * @public
- *
  * @defaultValue
  * ```ts
  * {
@@ -310,6 +493,8 @@ declare interface CreateProfileParams {
  *
  * @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;
@@ -321,13 +506,15 @@ export declare const DEFAULT_PAGE_PROPERTIES: {
 };
 
 /**
- * Internal helper class for building analytics and personalization events.
+ * 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 {
@@ -372,7 +559,6 @@ export declare class EventBuilder {
      *
      * @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.
@@ -392,39 +578,76 @@ export declare class EventBuilder {
      * @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;
+    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.
      *
-     * @public
-     *
      * @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.
      *
-     * @public
-     *
      * @remarks
      * This is a specialized variant of {@link EventBuilder.buildComponentView}
      * that sets `componentType` to `'Variable'`.
@@ -433,9 +656,13 @@ export declare class EventBuilder {
      * ```ts
      * const event = builder.buildFlagView({
      *   componentId: 'feature-flag-key',
+     *   componentViewId: crypto.randomUUID(),
      *   experienceId: 'personalization-123',
+     *   viewDurationMs: 1_000,
      * })
      * ```
+     *
+     * @public
      */
     buildFlagView(args: ComponentViewBuilderArgs): ComponentViewEvent;
     /**
@@ -444,8 +671,6 @@ export declare class EventBuilder {
      * @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
@@ -458,6 +683,8 @@ export declare class EventBuilder {
      *   traits: { plan: 'pro' },
      * })
      * ```
+     *
+     * @public
      */
     buildIdentify(args: IdentifyBuilderArgs): IdentifyEvent;
     /**
@@ -466,8 +693,6 @@ export declare class EventBuilder {
      * @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
@@ -483,6 +708,8 @@ export declare class EventBuilder {
      *   },
      * })
      * ```
+     *
+     * @public
      */
     buildPageView(args?: PageViewBuilderArgs): PageViewEvent;
     /**
@@ -491,8 +718,6 @@ export declare class EventBuilder {
      * @param args - {@link ScreenViewBuilderArgs} arguments for the screen view event.
      * @returns A {@link ScreenViewEvent} payload.
      *
-     * @public
-     *
      * @example
      * ```ts
      * const event = builder.buildScreenView({
@@ -502,6 +727,8 @@ export declare class EventBuilder {
      *   },
      * })
      * ```
+     *
+     * @public
      */
     buildScreenView(args: ScreenViewBuilderArgs): ScreenViewEvent;
     /**
@@ -510,8 +737,6 @@ export declare class EventBuilder {
      * @param args - {@link TrackBuilderArgs} arguments describing the tracked event.
      * @returns A {@link TrackEvent} payload.
      *
-     * @public
-     *
      * @example
      * ```ts
      * const event = builder.buildTrack({
@@ -519,6 +744,8 @@ export declare class EventBuilder {
      *   properties: { id: 'primary-cta', location: 'hero' },
      * })
      * ```
+     *
+     * @public
      */
     buildTrack(args: TrackBuilderArgs): TrackEvent_2;
 }
@@ -526,7 +753,6 @@ export declare class EventBuilder {
 /**
  * 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.).
@@ -548,6 +774,8 @@ export declare class EventBuilder {
  *   }),
  * })
  * ```
+ *
+ * @public
  */
 export declare interface EventBuilderConfig {
     /**
@@ -611,8 +839,6 @@ export declare const EXPERIENCE_BASE_URL = "https://experience.ninetailed.co/";
 /**
  * Client for interacting with the Experience API.
  *
- * @public
- *
  * @remarks
  * This client is responsible for reading and mutating Ninetailed profiles
  * using the Experience API.
@@ -626,6 +852,10 @@ export declare const EXPERIENCE_BASE_URL = "https://experience.ninetailed.co/";
  *
  * const profile = await client.getProfile('profile-id')
  * ```
+ *
+ * @see {@link ApiClientBase}
+ *
+ * @public
  */
 declare class ExperienceApiClient extends ApiClientBase {
     /**
@@ -732,8 +962,9 @@ declare class ExperienceApiClient extends ApiClientBase {
        * @returns The list of profiles affected by the batch operation.
        *
        * @remarks
-       * Every event must contain an anonymous ID. Profiles will be created or
-       * updated according to the anonymous ID.
+       * 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.
        *
@@ -741,13 +972,13 @@ declare class ExperienceApiClient extends ApiClientBase {
        * ```ts
        * const profiles = await client.upsertManyProfiles({
        *   events: [
-       *     [{ type: 'identify', userId: 'user-1' }],
-       *     [{ type: 'identify', userId: 'user-2' }],
+       *     { anonymousId: 'anon-1', type: 'identify', ... },
+       *     { anonymousId: 'anon-2', type: 'identify', ... },
        *   ],
        * })
        * ```
        */
-      upsertManyProfiles({ events }: BatchUpdateProfileParams, options?: RequestOptions): Promise<BatchExperienceData['profiles']>;
+      upsertManyProfiles({ events }: BatchUpdateProfileParams, options?: RequestOptions): Promise<BatchExperienceResponseData['profiles']>;
       /**
        * Constructs a request URL with query parameters derived from request options.
        *
@@ -776,16 +1007,30 @@ declare class ExperienceApiClient extends ApiClientBase {
        * @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';
 
@@ -796,8 +1041,6 @@ declare class ExperienceApiClient extends ApiClientBase {
       * @param init - Initialization options passed to `fetch`.
       * @returns A promise that resolves with the {@link Response}.
       *
-      * @public
-      *
       * @remarks
       * This abstraction allows the underlying implementation to be replaced,
       * for example in tests or different runtime environments.
@@ -808,16 +1051,18 @@ declare class ExperienceApiClient extends ApiClientBase {
       *   return fetch(url, init)
       * }
       * ```
+      *
+      * @public
       */
      declare type FetchMethod = (url: string | URL, init: RequestInit) => Promise<Response>;
 
      /**
       * Options passed to callback functions invoked by fetch wrappers.
       *
-      * @public
-      *
       * @remarks
       * Not all fields are guaranteed to be present in all callback scenarios.
+      *
+      * @public
       */
      declare interface FetchMethodCallbackOptions {
          /**
@@ -848,9 +1093,10 @@ declare class ExperienceApiClient extends ApiClientBase {
      /**
       * Arguments for constructing identify events.
       *
-      * @public
       * @remarks
       * Traits are merged by the API; only specified properties may be overwritten.
+      *
+      * @public
       */
      export declare type IdentifyBuilderArgs = z.infer<typeof IdentifyBuilderArgs_2>;
 
@@ -896,9 +1142,10 @@ declare class ExperienceApiClient extends ApiClientBase {
      /**
       * Arguments for constructing identify events.
       *
-      * @public
       * @remarks
       * Traits are merged by the API; only specified properties may be overwritten.
+      *
+      * @public
       */
      declare type IdentifyBuilderArgs = z.infer<typeof IdentifyBuilderArgs_2>;
 
@@ -912,8 +1159,6 @@ declare class ExperienceApiClient extends ApiClientBase {
      /**
       * Client for sending analytics and insights events to the Ninetailed Insights API.
       *
-      * @public
-      *
       * @remarks
       * This client is optimized for sending batched events, optionally using a
       * custom beacon-like handler when available.
@@ -923,7 +1168,6 @@ declare class ExperienceApiClient extends ApiClientBase {
       * const insightsClient = new InsightsApiClient({
       *   clientId: 'org-id',
       *   environment: 'main',
-      *   preview: false,
       * })
       *
       * await insightsClient.sendBatchEvents([
@@ -939,6 +1183,10 @@ declare class ExperienceApiClient extends ApiClientBase {
       *   }
       * ])
       * ```
+      *
+      * @see {@link ApiClientBase}
+      *
+      * @public
       */
      declare class InsightsApiClient extends ApiClientBase {
          /**
@@ -971,7 +1219,8 @@ declare class ExperienceApiClient extends ApiClientBase {
           *
           * @param batches - Array of event batches to send.
           * @param options - Optional request options, including a per-call `beaconHandler`.
-          * @returns A promise that resolves when the events have been sent or queued.
+          * @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
@@ -982,9 +1231,6 @@ declare class ExperienceApiClient extends ApiClientBase {
           * If the handler is missing or returns `false`, the events are emitted
           * immediately via `fetch`.
           *
-          * @returns A boolean value that is true when either the event batch is successfully
-          * queued by the beacon handler or a direct request is successfully sent.
-          *
           * @example
           * ```ts
           * const success = await insightsClient.sendBatchEvents(batches)
@@ -1014,10 +1260,11 @@ declare class ExperienceApiClient extends ApiClientBase {
      /**
       * Arguments for constructing page view events.
       *
-      * @public
       * @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>;
 
@@ -1069,21 +1316,29 @@ declare class ExperienceApiClient extends ApiClientBase {
      /**
       * Arguments for constructing page view events.
       *
-      * @public
       * @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 {
          /**
@@ -1129,7 +1384,7 @@ declare class ExperienceApiClient extends ApiClientBase {
      /**
       * Options that control how Insights events are sent.
       *
-      * @public
+      * @internal
       */
      declare interface RequestOptions_2 {
          /**
@@ -1149,13 +1404,14 @@ declare class ExperienceApiClient extends ApiClientBase {
 
      /**
       * Configuration options for {@link createRetryFetchMethod}.
+      *
+      * @public
       */
      declare interface RetryFetchMethodOptions extends BaseFetchMethodOptions {
          /**
           * Delay (in milliseconds) between retry attempts.
           *
-          * @remarks
-          * Defaults to {@link DEFAULT_INTERVAL_TIMEOUT}.
+          * @defaultValue `0`
           */
          intervalTimeout?: number;
          /**
@@ -1171,8 +1427,7 @@ declare class ExperienceApiClient extends ApiClientBase {
          /**
           * Maximum number of retry attempts.
           *
-          * @remarks
-          * Defaults to {@link DEFAULT_RETRY_COUNT}.
+          * @defaultValue `1`
           */
          retries?: number;
      }
@@ -1180,10 +1435,11 @@ declare class ExperienceApiClient extends ApiClientBase {
      /**
       * Arguments for constructing screen view events.
       *
-      * @public
       * @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>;
 
@@ -1229,15 +1485,18 @@ declare class ExperienceApiClient extends ApiClientBase {
      /**
       * Arguments for constructing screen view events.
       *
-      * @public
       * @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 {
          /**
@@ -1254,8 +1513,7 @@ declare class ExperienceApiClient extends ApiClientBase {
          /**
           * Maximum time (in milliseconds) to wait for a response before aborting the request.
           *
-          * @remarks
-          * Defaults to {@link DEFAULT_REQUEST_TIMEOUT}.
+          * @defaultValue `3000`
           */
          requestTimeout?: number;
      }
@@ -1366,6 +1624,8 @@ declare class ExperienceApiClient extends ApiClientBase {
 
      /**
       * Parameters used when updating an existing profile.
+      *
+      * @internal
       */
      declare interface UpdateProfileParams extends CreateProfileParams {
          /**
@@ -1376,6 +1636,8 @@ declare class ExperienceApiClient extends ApiClientBase {
 
      /**
       * Parameters used when creating or updating a profile.
+      *
+      * @internal
       */
      declare interface UpsertProfileParams extends CreateProfileParams {
          /**
@@ -1384,7 +1646,4 @@ declare class ExperienceApiClient extends ApiClientBase {
          profileId?: string;
      }
 
-
-     export * from "@contentful/optimization-api-schemas";
-
      export { }