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

package/dist/index.d.mts

@@ -1,58 +1,63 @@
-import { App } from '@contentful/optimization-api-schemas';
-import { BatchExperienceData } from '@contentful/optimization-api-schemas';
+/**
+ * @packageDocumentation
+ *
+ * The Contentful Optimization API Client Library provides methods for
+ * interfacing with Contentful's Experience and Insights APIs, which serve its
+ * Optimization and Analytics products.
+ */
+
 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 { 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.
  *
- * @public
- *
  * @remarks
  * This client encapsulates shared configuration and exposes dedicated
- * sub-clients for personalization and analytics use cases.
+ * sub-clients for experience and insights use cases.
  *
  * @example
  * ```ts
  * const client = new ApiClient({
  *   clientId: 'org-id',
  *   environment: 'main',
- *   preview: false,
- *   personalization: {
+ *   experience: {
  *     // experience-specific overrides
  *   },
- *   analytics: {
+ *   insights: {
  *     // insights-specific overrides
  *   },
  * })
  *
  * 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.
+     * Client for experience-related operations.
+     *
+     * @see {@link ExperienceApiClient}
      */
     readonly experience: ExperienceApiClient;
     /**
-     * Client for analytics and insights-related operations.
+     * Client for insights-related operations.
+     *
+     * @see {@link InsightsApiClient}
      */
     readonly insights: InsightsApiClient;
     /**
@@ -66,13 +71,11 @@ 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.
+ * must not be treated as part of the public API surface.
  *
- * Concrete API clients should extend this class to inherit consistent logging
+ * Concrete API clients must extend this class to inherit consistent logging
  * behavior and fetch configuration.
  *
  * @example
@@ -92,6 +95,8 @@ export declare class ApiClient {
  *   }
  * }
  * ```
+ *
+ * @internal
  */
 declare abstract class ApiClientBase {
     /**
@@ -124,8 +129,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.
@@ -142,25 +145,25 @@ declare abstract class ApiClientBase {
  */
 export declare interface ApiClientConfig extends Pick<ApiConfig, GlobalApiConfigProperties> {
     /**
-     * Configuration for the personalization (Experience) API client.
+     * Configuration for the 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>;
+    experience?: Omit<ExperienceApiClientConfig, GlobalApiConfigProperties>;
     /**
-     * Configuration for the analytics (Insights) API client.
+     * Configuration for the 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>;
+    insights?: Omit<InsightsApiClientConfig, GlobalApiConfigProperties>;
 }
 
 /**
- * Configuration options for API clients extending {@link ApiClientBase}.
+ * Configuration options for API clients extending `ApiClientBase`.
  *
  * @public
  */
@@ -176,8 +179,7 @@ export declare interface ApiConfig {
     /**
      * Contentful environment identifier.
      *
-     * @remarks
-     * Defaults to `main` when not provided.
+     * @defaultValue `'main'`
      */
     environment?: string;
     /**
@@ -198,7 +200,7 @@ export declare interface ApiConfig {
  *
  * @public
  */
-declare interface BaseFetchMethodOptions {
+export declare interface BaseFetchMethodOptions {
     /**
      * Human-readable name of the API being called.
      *
@@ -211,15 +213,18 @@ declare interface BaseFetchMethodOptions {
      *
      * @remarks
      * This is useful for providing polyfills, mocks, or instrumented fetch
-     * implementations.
+     * implementations. It is required in runtimes that do not provide
+     * `globalThis.fetch`.
      */
     fetchMethod?: FetchMethod;
 }
 
 /**
  * Parameters used when performing a batch profile update.
+ *
+ * @public
  */
-declare interface BatchUpdateProfileParams {
+export declare interface BatchUpdateProfileParams {
     /**
      * Batch of events to process.
      */
@@ -227,1164 +232,637 @@ declare interface BatchUpdateProfileParams {
 }
 
 /**
- * Arguments for constructing component view events.
+ * Parameters used when creating a profile.
  *
  * @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>>;
-}, z.core.$strip>;
+export declare interface CreateProfileParams {
+    /**
+     * Events used to aggregate the profile state.
+     */
+    events: ExperienceEventArray;
+}
 
 /**
- * Arguments for constructing component view events.
+ * Creates a {@link FetchMethod} that combines timeout and retry protection.
+ *
+ * @param options - Configuration options for both timeout and retry behavior.
+ * @returns A {@link FetchMethod} that applies timeout and retry logic to requests.
+ *
+ * @throws Error
+ * Rethrows the original error after logging, including abort errors.
+ *
+ * @remarks
+ * The resulting method first wraps the base fetch with a timeout (via
+ * {@link createTimeoutFetchMethod}), then applies retry behavior (via
+ * {@link createRetryFetchMethod}).
+ *
+ * If an error is thrown during configuration or request execution, it is logged.
+ *
+ * @example
+ * ```ts
+ * const fetchProtected = createProtectedFetchMethod({
+ *   apiName: 'Optimization',
+ *   requestTimeout: 4000,
+ *   retries: 2,
+ * })
+ *
+ * const response = await fetchProtected('https://example.com/experiences', {
+ *   method: 'GET',
+ * })
+ * ```
  *
  * @public
  */
-declare type ComponentViewBuilderArgs = z.infer<typeof ComponentViewBuilderArgs_2>;
+export declare function createProtectedFetchMethod(options: ProtectedFetchMethodOptions): FetchMethod;
 
 /**
- * Parameters used when creating a profile.
+ * Creates a {@link FetchMethod} that retries failed requests according to the
+ * provided configuration.
+ *
+ * @param options - Configuration options that control retry behavior.
+ * @returns A {@link FetchMethod} that automatically retries qualifying failures.
+ *
+ * @throws Error
+ * Thrown when the request cannot be retried and no successful response is obtained.
+ *
+ * @remarks
+ * This wrapper uses a lightweight internal retry loop and an {@link AbortController}
+ * to cancel pending requests when a non-retriable error occurs.
+ *
+ * @example
+ * ```ts
+ * const fetchWithRetry = createRetryFetchMethod({
+ *   apiName: 'Optimization',
+ *   retries: 3,
+ *   intervalTimeout: 200,
+ *   onFailedAttempt: ({ attemptNumber, retriesLeft }) => {
+ *     console.warn(`Attempt ${attemptNumber} failed. Retries left: ${retriesLeft}`)
+ *   },
+ * })
+ *
+ * const response = await fetchWithRetry('https://example.com', { method: 'GET' })
+ * ```
+ *
+ * @public
  */
-declare interface CreateProfileParams {
-    /**
-     * Events used to aggregate the profile state.
-     */
-    events: ExperienceEventArray;
-}
+export declare function createRetryFetchMethod({ apiName, fetchMethod, intervalTimeout, onFailedAttempt, retries, }?: RetryFetchMethodOptions): FetchMethod;
 
 /**
- * Default page properties used when no explicit page information is available.
+ * Creates a {@link FetchMethod} that aborts requests after a configurable timeout.
  *
- * @public
+ * @param options - Configuration options controlling timeout behavior.
+ * @returns A {@link FetchMethod} that enforces a timeout for each request.
  *
- * @defaultValue
+ * @remarks
+ * When a timeout occurs, the request is aborted using an {@link AbortController}.
+ * If `onRequestTimeout` is not provided, an error is logged by the package logger.
+ *
+ * @example
  * ```ts
- * {
- *   path: '',
- *   query: {},
- *   referrer: '',
- *   search: '',
- *   title: '',
- *   url: '',
- * }
+ * const fetchWithTimeout = createTimeoutFetchMethod({
+ *   apiName: 'Optimization',
+ *   requestTimeout: 5000,
+ *   onRequestTimeout: ({ apiName }) => {
+ *     console.warn(`${apiName} request timed out`)
+ *   },
+ * })
+ *
+ * const response = await fetchWithTimeout('https://example.com', { method: 'GET' })
  * ```
  *
- * @remarks
- * Values are required by the API; values may not be `undefined`. Empty values are valid.
+ * @see {@link TimeoutFetchMethodOptions}
+ *
+ * @public
  */
-export declare const DEFAULT_PAGE_PROPERTIES: {
-    path: string;
-    query: {};
-    referrer: string;
-    search: string;
-    title: string;
-    url: string;
-};
+export declare function createTimeoutFetchMethod({ apiName, fetchMethod, onRequestTimeout, requestTimeout, }?: TimeoutFetchMethodOptions): FetchMethod;
 
 /**
- * Internal helper class for building analytics and personalization events.
+ * 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 class coordinates configuration and argument validation to produce
- * strongly-typed event payloads compatible with
- * `@contentful/optimization-api-schemas`.
+ * 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')
+ * ```
+ *
+ * Extends `ApiClientBase`.
  *
  * @public
  */
-export declare class EventBuilder {
-    /**
-     * Application metadata attached to each event.
-     *
-     * @internal
-     */
-    app?: App;
-    /**
-     * Channel value attached to each event.
-     *
-     * @internal
-     */
-    channel: Channel;
+export declare class ExperienceApiClient extends ApiClientBase {
     /**
-     * Library metadata attached to each event.
-     *
-     * @internal
+     * Base URL used for Experience API requests.
      */
-    library: Library;
+    protected readonly baseUrl: string;
+    private readonly enabledFeatures?;
+    private readonly ip?;
+    private locale?;
+    private readonly plainText?;
+    private readonly preflight?;
     /**
-     * Function that provides the locale when available.
+     * Creates a new {@link ExperienceApiClient} instance.
      *
-     * @internal
+     * @param config - Configuration for the Experience API client.
      */
-    getLocale: () => string | undefined;
+    constructor(config: ExperienceApiClientConfig);
     /**
-     * Function that provides baseline page properties.
+     * Update the default Experience API locale used when request options omit `locale`.
      *
-     * @internal
-     */
-    getPageProperties: () => Page;
-    /**
-     * Function that provides the user agent string when available.
+     * @param locale - Next default Experience API locale.
      *
-     * @internal
+     * @public
      */
-    getUserAgent: () => string | undefined;
+    setLocale(locale: ExperienceApiClientRequestOptions['locale']): void;
     /**
-     * Creates a new {@link EventBuilder} instance.
+     * Retrieves a profile by ID.
      *
-     * @param config - Configuration used to customize event payloads.
+     * @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.
      *
-     * @internal
-     * @remarks
-     * Callers are expected to reuse a single instance when possible to avoid
-     * repeatedly reconfiguring the builder.
+     * @throws Error
+     * Thrown if `id` is missing or the underlying request fails.
      *
      * @example
      * ```ts
-     * const builder = new EventBuilder({
-     *   channel: 'web',
-     *   library: { name: '@contentful/optimization-sdk', version: '1.0.0' },
+     * const profile = await client.getProfile('profile-id', {
+     *   locale: 'en-US',
      * })
      * ```
      */
-    constructor(config: EventBuilderConfig);
+    getProfile(id: string, options?: Omit<ExperienceApiClientRequestOptions, 'preflight' | 'plainText'>): Promise<OptimizationData>;
     /**
-     * Builds the universal event properties shared across all event types.
+     * Sends a POST request to mutate a profile or profiles.
      *
-     * @param args - Arguments overriding the default context values.
-     * @returns A fully populated {@link UniversalEventProperties} object.
+     * @param request - Mutation request options including URL, body, and request options.
+     * @returns The raw {@link Response} from the underlying fetch.
      *
-     * @protected
-     *
-     * @remarks
-     * This method is used internally by the specific event-builder methods
-     * (e.g. {@link EventBuilder.buildPageView}).
+     * @internal
      */
-    protected buildUniversalEventProperties({ campaign, locale, location, page, screen, userAgent, }: UniversalEventBuilderArgs): UniversalEventProperties;
+    private makeProfileMutationRequest;
     /**
-     * Builds a component view event payload for a Contentful entry-based component.
+     * Creates a profile and returns the resulting optimization data.
      *
-     * @param args - {@link ComponentViewBuilderArgs} arguments describing the component view.
-     * @returns A {@link ComponentViewEvent} describing the view.
+     * @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.
      *
-     * @public
+     * @remarks
+     * The returned profile ID can be used for subsequent update requests.
      *
      * @example
      * ```ts
-     * const event = builder.buildComponentView({
-     *   componentId: 'entry-123',
-     *   experienceId: 'personalization-123',
-     *   variantIndex: 1,
+     * const data = await client.createProfile({
+     *   events: [{ type: 'identify', userId: 'user-123' }],
      * })
      * ```
      */
-    buildComponentView(args: ComponentViewBuilderArgs): ComponentViewEvent;
+    createProfile({ events }: CreateProfileParams, options?: ExperienceApiClientRequestOptions): Promise<OptimizationData>;
     /**
-     * Builds a component view event payload for a Custom Flag component.
+     * Updates an existing profile with the given profile ID.
      *
-     * @param args - {@link ComponentViewBuilderArgs} arguments describing the Custom Flag view.
-     * @returns A {@link ComponentViewEvent} describing the view.
+     * @param params - Parameters including the profile ID and events.
+     * @param options - Optional request options.
+     * @returns The updated optimization data for the profile.
      *
-     * @public
-     *
-     * @remarks
-     * This is a specialized variant of {@link EventBuilder.buildComponentView}
-     * that sets `componentType` to `'Variable'`.
+     * @throws Error
+     * Thrown if `profileId` is missing or the underlying request fails.
      *
      * @example
      * ```ts
-     * const event = builder.buildFlagView({
-     *   componentId: 'feature-flag-key',
-     *   experienceId: 'personalization-123',
+     * const data = await client.updateProfile({
+     *   profileId: 'profile-id',
+     *   events: [{ type: 'track', event: 'viewed_video' }],
      * })
      * ```
      */
-    buildFlagView(args: ComponentViewBuilderArgs): ComponentViewEvent;
+    updateProfile({ profileId, events }: UpdateProfileParams, options?: ExperienceApiClientRequestOptions): Promise<OptimizationData>;
     /**
-     * Builds an identify event payload to associate a user ID with traits.
-     *
-     * @param args - {@link IdentifyBuilderArgs} arguments describing the identified user.
-     * @returns An {@link IdentifyEvent} payload.
-     *
-     * @public
+     * Creates or updates a profile depending on whether a `profileId` is provided.
      *
-     * @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.
+     * @param params - Parameters including optional profile ID and events.
+     * @param options - Optional request options.
+     * @returns The resulting optimization data.
      *
      * @example
      * ```ts
-     * const event = builder.buildIdentify({
-     *   userId: 'user-123',
-     *   traits: { plan: 'pro' },
-     * })
+     * // Create
+     * await client.upsertProfile({ events })
+     *
+     * // Update
+     * await client.upsertProfile({ profileId: 'profile-id', events })
      * ```
      */
-    buildIdentify(args: IdentifyBuilderArgs): IdentifyEvent;
+    upsertProfile({ profileId, events }: UpsertProfileParams, options?: ExperienceApiClientRequestOptions): Promise<OptimizationData>;
     /**
-     * Builds a page view event payload.
-     *
-     * @param args - Optional {@link PageViewBuilderArgs} overrides for the page view event.
-     * @returns A {@link PageViewEvent} payload.
+     * Sends multiple events to the Ninetailed Experience API to upsert many profiles.
      *
-     * @public
+     * @param params - Parameters containing the batch of events.
+     * @param options - Optional request options.
+     * @returns The list of profiles affected by the batch operation.
      *
      * @remarks
-     * Page properties are created by merging:
-     * 1. The base page properties from {@link EventBuilderConfig.getPageProperties}, and
-     * 2. The partial `properties` argument passed in.
+     * 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.
      *
-     * The title always falls back to {@link DEFAULT_PAGE_PROPERTIES}.title when undefined.
+     * This method is intended to be used from server environments.
      *
      * @example
      * ```ts
-     * const event = builder.buildPageView({
-     *   properties: {
-     *     title: 'Homepage',
-     *   },
+     * const profiles = await client.upsertManyProfiles({
+     *   events: [
+     *     { anonymousId: 'anon-1', type: 'identify', ... },
+     *     { anonymousId: 'anon-2', type: 'identify', ... },
+     *   ],
      * })
      * ```
      */
-    buildPageView(args?: PageViewBuilderArgs): PageViewEvent;
+    upsertManyProfiles({ events }: BatchUpdateProfileParams, options?: ExperienceApiClientRequestOptions): Promise<BatchExperienceResponseData['profiles']>;
     /**
-     * Builds a screen view event payload.
+     * Constructs a request URL with query parameters derived from request options.
      *
-     * @param args - {@link ScreenViewBuilderArgs} arguments for the screen view event.
-     * @returns A {@link ScreenViewEvent} payload.
+     * @param path - Path relative to the Experience API base URL.
+     * @param options - Request options that can influence query parameters.
+     * @returns The fully constructed URL as a string.
      *
-     * @public
+     * @internal
+     */
+    private constructUrl;
+    /**
+     * Constructs request headers based on request options and default configuration.
      *
-     * @example
-     * ```ts
-     * const event = builder.buildScreenView({
-     *   name: 'home',
-     *   properties: {
-     *     title: 'Home Screen',
-     *   },
-     * })
-     * ```
+     * @param options - Request options that can influence headers.
+     * @returns A record of HTTP headers to send with the request.
+     *
+     * @internal
      */
-    buildScreenView(args: ScreenViewBuilderArgs): ScreenViewEvent;
+    private constructHeaders;
     /**
-     * Builds a track event payload for arbitrary user actions.
+     * Constructs the `options` section of the request body for profile mutations.
      *
-     * @param args - {@link TrackBuilderArgs} arguments describing the tracked event.
-     * @returns A {@link TrackEvent} payload.
+     * @param options - Request options that can specify enabled features.
+     * @returns Experience API body options including feature flags.
      *
-     * @public
+     * @internal
+     */
+    private readonly constructBodyOptions;
+    /**
+     * Construct and validate the singular Experience mutation request payload.
      *
-     * @example
-     * ```ts
-     * const event = builder.buildTrack({
-     *   event: 'button_clicked',
-     *   properties: { id: 'primary-cta', location: 'hero' },
-     * })
-     * ```
+     * @param events - Events for the Experience API to evaluate.
+     * @param options - Request options that can contribute body options.
+     * @returns Validated singular Experience request body.
+     *
+     * @internal
      */
-    buildTrack(args: TrackBuilderArgs): TrackEvent_2;
+    private constructExperienceRequestBody;
 }
 
 /**
- * Configuration options for creating an {@link EventBuilder} instance.
+ * Configuration for {@link ExperienceApiClient}.
  *
  * @public
- * @remarks
- * The configuration is typically provided by the host application to adapt
- * event payloads to the runtime environment (browser, framework, etc.).
+ */
+export declare interface ExperienceApiClientConfig extends ApiConfig, ExperienceApiClientRequestOptions {
+}
+
+/**
+ * Options that control how requests to the Experience API are handled.
  *
- * @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 {
+export declare interface ExperienceApiClientRequestOptions {
     /**
-     * The application definition used to attribute events to a specific consumer app.
+     * Enabled features (for example, `"ip-enrichment"`) for the API to use for this request.
      *
      * @remarks
-     * When not provided, events will not contain app metadata in their context.
+     * When omitted, the API can apply a default set of features.
      */
-    app?: App;
+    enabledFeatures?: Feature[];
     /**
-     * The channel that identifies where events originate from (e.g. web, mobile).
+     * IP address to override the API behavior for IP analysis.
      *
-     * @see {@link Channel}
+     * @remarks
+     * Commonly used in ESR or SSR environments, as the API otherwise uses
+     * the server IP.
      */
-    channel: Channel;
+    ip?: string;
     /**
-     * The client library metadata that is attached to all events.
+     * Experience API `locale` query parameter used to translate profile location fields such as
+     * `location.city` and `location.country`.
      *
      * @remarks
-     * This is typically used to record the library name and version.
+     * When omitted, the API can use a server-side default.
      */
-    library: Library;
+    locale?: string;
     /**
-     * Function used to resolve the locale for outgoing events.
+     * When `true`, sends performance-critical endpoints in plain text.
      *
      * @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.
+     * The Ninetailed API accepts certain endpoints in plain text to avoid CORS
+     * preflight requests, which can improve performance in browser environments.
      */
-    getLocale?: () => string | undefined;
+    plainText?: boolean;
     /**
-     * Function that returns the current page properties.
+     * When `true`, instructs the API to aggregate a new profile state but not store it.
      *
      * @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}
+     * This is commonly used in ESR or SSR environments where you want to
+     * preview the result without persisting changes.
      */
-    getPageProperties?: () => Page;
+    preflight?: boolean;
+}
+
+/**
+ * Feature flags supported by the Experience API.
+ *
+ * @internal
+ */
+export 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 (input, init) => {
+ *   return fetch(input, init)
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare type FetchInput = string | Request;
+
+export declare type FetchMethod = (input: FetchInput, 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
+ */
+export declare interface FetchMethodCallbackOptions {
     /**
-     * Function used to obtain the current user agent string when applicable.
-     *
-     * @returns A user agent string, or `undefined` if unavailable.
+     * 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).
      */
-    getUserAgent?: () => string | undefined;
+    attemptNumber?: number;
+    /**
+     * Number of retry attempts remaining (for retry callbacks).
+     */
+    retriesLeft?: number;
 }
 
 /**
- * Default base URL for the Experience API.
+ * Properties that can be shared between global and per-client API configuration.
  *
  * @public
  */
-export declare const EXPERIENCE_BASE_URL = "https://experience.ninetailed.co/";
+export declare type GlobalApiConfigProperties = 'environment' | 'fetchOptions' | 'clientId';
 
 /**
- * Client for interacting with the Experience API.
+ * 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 responsible for reading and mutating Ninetailed profiles
- * using the Experience API.
+ * This client is optimized for sending batched events, optionally using a
+ * custom beacon-like sender for last-chance lifecycle delivery.
  *
  * @example
  * ```ts
- * const client = new ExperienceApiClient({
+ * const insightsClient = new InsightsApiClient({
  *   clientId: 'org-id',
  *   environment: 'main',
  * })
  *
- * const profile = await client.getProfile('profile-id')
+ * await insightsClient.sendBatchEvents([
+ *   {
+ *     profile: { id: 'profile-123', ... },
+ *     events: [
+ *       {
+ *         type: 'track',
+ *         event: 'button_clicked',
+ *         properties: { id: 'primary-cta' },
+ *       },
+ *     ],
+ *   }
+ * ])
  * ```
+ *
+ * Extends `ApiClientBase`.
+ *
+ * @public
  */
-declare class ExperienceApiClient extends ApiClientBase {
+export declare class InsightsApiClient extends ApiClientBase {
     /**
-     * Base URL used for Experience API requests.
+     * Base URL used for Insights 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.
+     * Creates a new {@link InsightsApiClient} instance.
      *
-     * @param config - Configuration for the Experience API client.
+     * @param config - Configuration for the Insights API client.
+     *
+     * @example
+     * ```ts
+     * const client = new InsightsApiClient({
+     *   clientId: 'org-id',
+     *   environment: 'main',
+     * })
+     * ```
      */
-    constructor(config: ExperienceApiClientConfig);
+    constructor(config: InsightsApiClientConfig);
     /**
-     * Retrieves a profile by ID.
+     * Sends batches of insights events to the Ninetailed Insights API.
      *
-     * @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.
+     * @param batches - Array of event batches to send.
+     * @param options - Optional request options, including a per-call `beacon` sender.
+     * @returns `true` when the event batch is successfully queued by the beacon
+     * sender or a direct request is successfully sent, `false` otherwise.
      *
-     * @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
-       * 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: [
-       *     [{ type: 'identify', userId: 'user-1' }],
-       *     [{ type: 'identify', userId: 'user-2' }],
-       *   ],
-       * })
-       * ```
-       */
-      upsertManyProfiles({ events }: BatchUpdateProfileParams, options?: RequestOptions): Promise<BatchExperienceData['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;
-     }
-
-     /**
-      * Configuration for {@link ExperienceApiClient}.
-      */
-     export declare interface ExperienceApiClientConfig extends ApiConfig, RequestOptions {
-     }
-
-     /**
-      * Feature flags supported by the Experience API.
-      */
-     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}.
-      *
-      * @public
-      *
-      * @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)
-      * }
-      * ```
-      */
-     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.
-      */
-     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.
-      *
-      * @public
-      * @remarks
-      * Traits are merged by the API; only specified properties may be overwritten.
-      */
-     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.
-      *
-      * @public
-      * @remarks
-      * Traits are merged by the API; only specified properties may be overwritten.
-      */
-     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.
-      *
-      * @public
-      *
-      * @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',
-      *   preview: false,
-      * })
-      *
-      * await insightsClient.sendBatchEvents([
-      *   {
-      *     profile: { id: 'profile-123', ... },
-      *     events: [
-      *       {
-      *         type: 'track',
-      *         event: 'button_clicked',
-      *         properties: { id: 'primary-cta' },
-      *       },
-      *     ],
-      *   }
-      * ])
-      * ```
-      */
-     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 A promise that resolves when the events have been sent or queued.
-          *
-          * @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`.
-          *
-          * @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)
-          * ```
-          *
-          * @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.
-      *
-      * @public
-      * @remarks
-      * Any properties passed here are merged with the base page properties from
-      * {@link EventBuilderConfig.getPageProperties}.
-      */
-     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.
-      *
-      * @public
-      * @remarks
-      * Any properties passed here are merged with the base page properties from
-      * {@link EventBuilderConfig.getPageProperties}.
-      */
-     declare type PageViewBuilderArgs = z.infer<typeof PageViewBuilderArgs_2>;
-
-     /**
-      * Options for {@link createProtectedFetchMethod}, combining timeout and retry behavior.
-      */
-     declare interface ProtectedFetchMethodOptions extends RetryFetchMethodOptions, TimeoutFetchMethodOptions {
-     }
-
-     /**
-      * Options that control how requests to the Experience API are handled.
-      */
-     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.
-      *
-      * @public
-      */
-     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}.
-      */
-     declare interface RetryFetchMethodOptions extends BaseFetchMethodOptions {
-         /**
-          * Delay (in milliseconds) between retry attempts.
-          *
-          * @remarks
-          * Defaults to {@link DEFAULT_INTERVAL_TIMEOUT}.
-          */
-         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.
-          *
-          * @remarks
-          * Defaults to {@link DEFAULT_RETRY_COUNT}.
-          */
-         retries?: number;
-     }
-
-     /**
-      * Arguments for constructing screen view events.
-      *
-      * @public
-      * @remarks
-      * Any properties passed here are merged with the base screen properties from
-      * {@link EventBuilderConfig.getScreenProperties}.
-      */
-     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.
-      *
-      * @public
-      * @remarks
-      * Any properties passed here are merged with the base screen properties from
-      * {@link EventBuilderConfig.getScreenProperties}.
-      */
-     declare type ScreenViewBuilderArgs = z.infer<typeof ScreenViewBuilderArgs_2>;
-
-     /**
-      * Configuration options for {@link createTimeoutFetchMethod}.
-      */
-     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.
-          *
-          * @remarks
-          * Defaults to {@link DEFAULT_REQUEST_TIMEOUT}.
-          */
-         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>;
+     * @remarks
+     * If a `beacon` sender is provided, it will be invoked first with the
+     * serialized request body. When the sender returns `true`, the events are
+     * considered successfully queued and no network request is made by this
+     * method.
+     *
+     * If the sender is missing, returns `false`, or throws, the events are
+     * emitted immediately via `fetch`.
+     *
+     * @example
+     * ```ts
+     * const success = await insightsClient.sendBatchEvents(batches)
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Use Beacon for a last-chance lifecycle flush
+     * const success = await insightsClient.sendBatchEvents(batches, {
+     *   beacon: (url, body) => navigator.sendBeacon(url, body),
+     * })
+     * ```
+     */
+    sendBatchEvents(batches: BatchInsightsEventArray, options?: InsightsApiClientRequestOptions): Promise<boolean>;
+}
 
-     /**
-      * Arguments used to construct the universal (shared) portion of all events.
-      *
-      * @public
-      */
-     export declare type UniversalEventBuilderArgs = z.infer<typeof UniversalEventBuilderArgs_2>;
+/**
+ * Configuration for {@link InsightsApiClient}.
+ *
+ * @public
+ */
+export declare interface InsightsApiClientConfig extends ApiConfig {
+}
 
-     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>;
+/**
+ * Options that control how Insights events are sent.
+ *
+ * @public
+ */
+export declare interface InsightsApiClientRequestOptions {
+    /**
+     * Sender used to enqueue serialized events via the Beacon API or a similar mechanism.
+     *
+     * @param url - Target URL for the batched events.
+     * @param body - Serialized batched insights events to be sent.
+     * @returns `true` if the events were successfully queued, `false` otherwise.
+     *
+     * @remarks
+     * This option is intended for last-chance lifecycle delivery. If it returns
+     * `false` or throws, the client falls back to emitting events immediately via
+     * `fetch` with `keepalive`.
+     */
+    beacon?: (url: string, body: string) => boolean;
+}
 
-     /**
-      * Arguments used to construct the universal (shared) portion of all events.
-      *
-      * @public
-      */
-     declare type UniversalEventBuilderArgs = z.infer<typeof UniversalEventBuilderArgs_2>;
+/**
+ * Options for {@link createProtectedFetchMethod}, combining timeout and retry behavior.
+ *
+ * @see {@link RetryFetchMethodOptions}
+ * @see {@link TimeoutFetchMethodOptions}
+ *
+ * @public
+ */
+export declare interface ProtectedFetchMethodOptions extends RetryFetchMethodOptions, TimeoutFetchMethodOptions {
+}
 
-     /**
-      * Parameters used when updating an existing profile.
-      */
-     declare interface UpdateProfileParams extends CreateProfileParams {
-         /**
-          * ID of the profile to update.
-          */
-         profileId: string;
-     }
+/**
+ * Configuration options for {@link createRetryFetchMethod}.
+ *
+ * @public
+ */
+export 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;
+}
 
-     /**
-      * Parameters used when creating or updating a profile.
-      */
-     declare interface UpsertProfileParams extends CreateProfileParams {
-         /**
-          * Optional ID of the profile; when omitted, a new profile is created.
-          */
-         profileId?: string;
-     }
+/**
+ * Configuration options for {@link createTimeoutFetchMethod}.
+ *
+ * @public
+ */
+export 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;
+}
 
+/**
+ * Parameters used when updating an existing profile.
+ *
+ * @public
+ */
+export declare interface UpdateProfileParams extends CreateProfileParams {
+    /**
+     * ID of the profile to update.
+     */
+    profileId: string;
+}
 
-     export * from "@contentful/optimization-api-schemas";
+/**
+ * Parameters used when creating or updating a profile.
+ *
+ * @public
+ */
+export declare interface UpsertProfileParams extends CreateProfileParams {
+    /**
+     * Optional ID of the profile; when omitted, a new profile is created.
+     */
+    profileId?: string;
+}
 
-     export { }
+export { }