@contentful/optimization-api-client 0.1.0-alpha → 0.1.0-alpha11

package/dist/index.d.mts

@@ -0,0 +1,865 @@
+/**
+ * @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 { ExperienceEventArray } from '@contentful/optimization-api-schemas';
+import { OptimizationData } from '@contentful/optimization-api-schemas';
+
+/**
+ * Aggregated API client providing access to Experience and Insights APIs.
+ *
+ * @remarks
+ * This client encapsulates shared configuration and exposes dedicated
+ * sub-clients for experience and insights use cases.
+ *
+ * @example
+ * ```ts
+ * const client = new ApiClient({
+ *   clientId: 'org-id',
+ *   environment: 'main',
+ *   experience: {
+ *     // experience-specific overrides
+ *   },
+ *   insights: {
+ *     // insights-specific overrides
+ *   },
+ * })
+ *
+ * const profile = await client.experience.getProfile('profile-id')
+ * await client.insights.sendBatchEvents(batches)
+ * ```
+ *
+ * @see {@link ExperienceApiClient}
+ * @see {@link InsightsApiClient}
+ *
+ * @public
+ */
+export declare class ApiClient {
+    /**
+     * Shared configuration applied to both Experience and Insights clients.
+     *
+     * @see {@link ApiConfig}
+     */
+    readonly config: ApiConfig;
+    /**
+     * Client for experience-related operations.
+     *
+     * @see {@link ExperienceApiClient}
+     */
+    readonly experience: ExperienceApiClient;
+    /**
+     * Client for insights-related operations.
+     *
+     * @see {@link InsightsApiClient}
+     */
+    readonly insights: InsightsApiClient;
+    /**
+     * Creates a new aggregated {@link ApiClient} instance.
+     *
+     * @param config - Global API client configuration with optional per-client overrides.
+     */
+    constructor(config: ApiClientConfig);
+}
+
+/**
+ * Base class for API clients that provides shared configuration and error logging.
+ *
+ * @remarks
+ * This abstract class is intended for internal use within the package and
+ * should not be treated as part of the public API surface.
+ *
+ * Concrete API clients should extend this class to inherit consistent logging
+ * behavior and fetch configuration.
+ *
+ * @example
+ * ```ts
+ * interface MyClientConfig extends ApiConfig {
+ *   // additional config
+ * }
+ *
+ * class MyClient extends ApiClientBase {
+ *   constructor(config: MyClientConfig) {
+ *     super('MyClient', config)
+ *   }
+ *
+ *   async getSomething() {
+ *     const response = await this.fetch('https://example.com', { method: 'GET' })
+ *     return response.json()
+ *   }
+ * }
+ * ```
+ *
+ * @internal
+ */
+declare abstract class ApiClientBase {
+    /**
+     * Name of the API client, used in log messages and as the `apiName` for fetch.
+     */
+    protected readonly name: string;
+    /**
+     * Client identifier used for authentication or tracking.
+     */
+    protected readonly clientId: string;
+    /**
+     * Contentful environment associated with this client.
+     */
+    protected readonly environment: string;
+    /**
+     * Protected fetch method used by the client to perform HTTP requests.
+     */
+    protected readonly fetch: FetchMethod;
+    /**
+     * Creates a new API client base instance.
+     *
+     * @param name - Human-readable name of the client (used for logging and `apiName`).
+     * @param config - Configuration options for the client.
+     */
+    constructor(name: string, { fetchOptions, clientId, environment }: ApiConfig);
+    /**
+     * Logs errors that occur during API requests with standardized messages.
+     *
+     * @param error - The error thrown by the underlying operation.
+     * @param options - Additional metadata about the request.
+     * @param options.requestName - Human-readable name of the request operation.
+     *
+     * @remarks
+     * Abort errors are logged at `warn` level and other errors at `error` level.
+     * The log message includes the client name for better debugging context.
+     */
+    protected logRequestError(error: unknown, { requestName }: {
+        requestName: string;
+    }): void;
+}
+
+/**
+ * Configuration for the high-level {@link ApiClient}.
+ *
+ * @public
+ */
+export declare interface ApiClientConfig extends Pick<ApiConfig, GlobalApiConfigProperties> {
+    /**
+     * Configuration for the Experience API client.
+     *
+     * @remarks
+     * Shared fields (`clientId`, `environment`, `fetchOptions`) are inherited
+     * from top-level config; this object is for Experience-specific options.
+     */
+    experience?: Omit<ExperienceApiClientConfig, GlobalApiConfigProperties>;
+    /**
+     * Configuration for the Insights API client.
+     *
+     * @remarks
+     * Shared fields (`clientId`, `environment`, `fetchOptions`) are inherited
+     * from top-level config; this object is for Insights-specific options.
+     */
+    insights?: Omit<InsightsApiClientConfig, GlobalApiConfigProperties>;
+}
+
+/**
+ * Configuration options for API clients extending `ApiClientBase`.
+ *
+ * @public
+ */
+export declare interface ApiConfig {
+    /**
+     * Base URL for the API.
+     *
+     * @remarks
+     * When omitted, the concrete client is expected to construct full URLs
+     * internally.
+     */
+    baseUrl?: string;
+    /**
+     * Contentful environment identifier.
+     *
+     * @defaultValue `'main'`
+     */
+    environment?: string;
+    /**
+     * Options used to configure the underlying protected fetch method.
+     *
+     * @remarks
+     * `apiName` is derived from the client name and must not be provided here.
+     */
+    fetchOptions?: Omit<ProtectedFetchMethodOptions, 'apiName'>;
+    /**
+     * Client identifier used for authentication or tracking.
+     */
+    clientId: string;
+}
+
+/**
+ * Base options shared across fetch method factories.
+ *
+ * @public
+ */
+export declare interface BaseFetchMethodOptions {
+    /**
+     * Human-readable name of the API being called.
+     *
+     * @remarks
+     * Used primarily for logging and error messages.
+     */
+    apiName?: string;
+    /**
+     * Custom fetch implementation to use instead of the global `fetch`.
+     *
+     * @remarks
+     * This is useful for providing polyfills, mocks, or instrumented fetch
+     * implementations.
+     */
+    fetchMethod?: FetchMethod;
+}
+
+/**
+ * Parameters used when performing a batch profile update.
+ *
+ * @public
+ */
+export declare interface BatchUpdateProfileParams {
+    /**
+     * Batch of events to process.
+     */
+    events: BatchExperienceEventArray;
+}
+
+/**
+ * Parameters used when creating a profile.
+ *
+ * @public
+ */
+export declare interface CreateProfileParams {
+    /**
+     * Events used to aggregate the profile state.
+     */
+    events: ExperienceEventArray;
+}
+
+/**
+ * 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
+ */
+export declare function createProtectedFetchMethod(options: ProtectedFetchMethodOptions): FetchMethod;
+
+/**
+ * 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
+ */
+export declare function createRetryFetchMethod({ apiName, fetchMethod, intervalTimeout, onFailedAttempt, retries, }?: RetryFetchMethodOptions): FetchMethod;
+
+/**
+ * Creates a {@link FetchMethod} that aborts requests after a configurable timeout.
+ *
+ * @param options - Configuration options controlling timeout behavior.
+ * @returns A {@link FetchMethod} that enforces a timeout for each request.
+ *
+ * @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
+ * const fetchWithTimeout = createTimeoutFetchMethod({
+ *   apiName: 'Optimization',
+ *   requestTimeout: 5000,
+ *   onRequestTimeout: ({ apiName }) => {
+ *     console.warn(`${apiName} request timed out`)
+ *   },
+ * })
+ *
+ * const response = await fetchWithTimeout('https://example.com', { method: 'GET' })
+ * ```
+ *
+ * @see {@link TimeoutFetchMethodOptions}
+ *
+ * @public
+ */
+export declare function createTimeoutFetchMethod({ apiName, fetchMethod, onRequestTimeout, requestTimeout, }?: TimeoutFetchMethodOptions): FetchMethod;
+
+/**
+ * Default base URL for the Experience API.
+ *
+ * @public
+ */
+export declare const EXPERIENCE_BASE_URL = "https://experience.ninetailed.co/";
+
+/**
+ * Client for interacting with the Experience API.
+ *
+ * @remarks
+ * This client is responsible for reading and mutating Ninetailed profiles
+ * using the Experience API.
+ *
+ * @example
+ * ```ts
+ * const client = new ExperienceApiClient({
+ *   clientId: 'org-id',
+ *   environment: 'main',
+ * })
+ *
+ * const profile = await client.getProfile('profile-id')
+ * ```
+ *
+ * Extends `ApiClientBase`.
+ *
+ * @public
+ */
+export declare class ExperienceApiClient extends ApiClientBase {
+    /**
+     * Base URL used for Experience API requests.
+     */
+    protected readonly baseUrl: string;
+    private readonly enabledFeatures?;
+    private readonly ip?;
+    private readonly locale?;
+    private readonly plainText?;
+    private readonly preflight?;
+    /**
+     * Creates a new {@link ExperienceApiClient} instance.
+     *
+     * @param config - Configuration for the Experience API client.
+     */
+    constructor(config: ExperienceApiClientConfig);
+    /**
+     * Retrieves a profile by ID.
+     *
+     * @param id - The profile ID to retrieve.
+     * @param options - Optional request options. `preflight` and `plainText` are not allowed here.
+     * @returns The current optimization data for the profile.
+     *
+     * @throws 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<ExperienceApiClientRequestOptions, '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?: ExperienceApiClientRequestOptions): 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 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?: ExperienceApiClientRequestOptions): 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?: ExperienceApiClientRequestOptions): Promise<OptimizationData>;
+    /**
+     * Sends multiple events to the Ninetailed Experience API to upsert many profiles.
+     *
+     * @param params - Parameters containing the batch of events.
+     * @param options - Optional request options.
+     * @returns The list of profiles affected by the batch operation.
+     *
+     * @remarks
+     * Batch requests must contain at least one event. Every event must contain
+     * an anonymous ID. Profiles will be created or updated according to the
+     * anonymous ID.
+     *
+     * This method is intended to be used from server environments.
+     *
+     * @example
+     * ```ts
+     * const profiles = await client.upsertManyProfiles({
+     *   events: [
+     *     { anonymousId: 'anon-1', type: 'identify', ... },
+     *     { anonymousId: 'anon-2', type: 'identify', ... },
+     *   ],
+     * })
+     * ```
+     */
+    upsertManyProfiles({ events }: BatchUpdateProfileParams, options?: ExperienceApiClientRequestOptions): Promise<BatchExperienceResponseData['profiles']>;
+    /**
+     * Constructs a request URL with query parameters derived from request options.
+     *
+     * @param path - Path relative to the Experience API base URL.
+     * @param options - Request options that may influence query parameters.
+     * @returns The fully constructed URL as a string.
+     *
+     * @internal
+     */
+    private constructUrl;
+    /**
+     * Constructs request headers based on request options and default configuration.
+     *
+     * @param options - Request options that may influence headers.
+     * @returns A record of HTTP headers to send with the request.
+     *
+     * @internal
+     */
+    private constructHeaders;
+    /**
+     * Constructs the `options` section of the request body for profile mutations.
+     *
+     * @param options - Request options that may specify enabled features.
+     * @returns Experience API body options including feature flags.
+     *
+     * @internal
+     */
+    private readonly constructBodyOptions;
+    /**
+     * Construct and validate the singular Experience mutation request payload.
+     *
+     * @param events - Events that should be evaluated by the Experience API.
+     * @param options - Request options that may contribute body options.
+     * @returns Validated singular Experience request body.
+     *
+     * @internal
+     */
+    private constructExperienceRequestBody;
+}
+
+/**
+ * Configuration for {@link ExperienceApiClient}.
+ *
+ * @public
+ */
+export declare interface ExperienceApiClientConfig extends ApiConfig, ExperienceApiClientRequestOptions {
+}
+
+/**
+ * Options that control how requests to the Experience API are handled.
+ *
+ * @public
+ */
+export declare interface ExperienceApiClientRequestOptions {
+    /**
+     * 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;
+}
+
+/**
+ * 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 (url, init) => {
+ *   return fetch(url, init)
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare type FetchMethod = (url: string | URL, init: RequestInit) => Promise<Response>;
+
+/**
+ * Options passed to callback functions invoked by fetch wrappers.
+ *
+ * @remarks
+ * Not all fields are guaranteed to be present in all callback scenarios.
+ *
+ * @public
+ */
+export 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';
+
+/**
+ * Default base URL for the Insights ingest API.
+ *
+ * @public
+ */
+export declare const INSIGHTS_BASE_URL = "https://ingest.insights.ninetailed.co/";
+
+/**
+ * Client for sending analytics and insights events to the Ninetailed Insights API.
+ *
+ * @remarks
+ * This client is optimized for sending batched events, optionally using a
+ * custom beacon-like handler when available.
+ *
+ * @example
+ * ```ts
+ * const insightsClient = new InsightsApiClient({
+ *   clientId: 'org-id',
+ *   environment: 'main',
+ * })
+ *
+ * await insightsClient.sendBatchEvents([
+ *   {
+ *     profile: { id: 'profile-123', ... },
+ *     events: [
+ *       {
+ *         type: 'track',
+ *         event: 'button_clicked',
+ *         properties: { id: 'primary-cta' },
+ *       },
+ *     ],
+ *   }
+ * ])
+ * ```
+ *
+ * Extends `ApiClientBase`.
+ *
+ * @public
+ */
+export declare class InsightsApiClient extends ApiClientBase {
+    /**
+     * Base URL used for Insights API requests.
+     */
+    protected readonly baseUrl: string;
+    /**
+     * Optional handler used to enqueue events via the Beacon API or a similar mechanism.
+     */
+    private readonly beaconHandler;
+    /**
+     * Creates a new {@link InsightsApiClient} instance.
+     *
+     * @param config - Configuration for the Insights API client.
+     *
+     * @example
+     * ```ts
+     * const client = new InsightsApiClient({
+     *   clientId: 'org-id',
+     *   environment: 'main',
+     *   beaconHandler: (url, data) => {
+     *     return navigator.sendBeacon(url.toString(), JSON.stringify(data))
+     *   },
+     * })
+     * ```
+     */
+    constructor(config: InsightsApiClientConfig);
+    /**
+     * Sends batches of insights events to the Ninetailed Insights API.
+     *
+     * @param batches - Array of event batches to send.
+     * @param options - Optional request options, including a per-call `beaconHandler`.
+     * @returns `true` when the event batch is successfully queued by the beacon
+     * handler or a direct request is successfully sent, `false` otherwise.
+     *
+     * @remarks
+     * If a `beaconHandler` is provided (either in the method call or in the
+     * client configuration) it will be invoked first. When the handler returns
+     * `true`, the events are considered successfully queued and no network
+     * request is made by this method.
+     *
+     * If the handler is missing or returns `false`, the events are emitted
+     * immediately via `fetch`.
+     *
+     * @example
+     * ```ts
+     * const success = await insightsClient.sendBatchEvents(batches)
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Override beaconHandler for a single call
+     * const success = await insightsClient.sendBatchEvents(batches, {
+     *   beaconHandler: (url, data) => {
+     *     return navigator.sendBeacon(url.toString(), JSON.stringify(data))
+     *   },
+     * })
+     * ```
+     */
+    sendBatchEvents(batches: BatchInsightsEventArray, options?: InsightsApiClientRequestOptions): Promise<boolean>;
+}
+
+/**
+ * Configuration for {@link InsightsApiClient}.
+ *
+ * @public
+ */
+export declare interface InsightsApiClientConfig extends ApiConfig, InsightsApiClientRequestOptions {
+}
+
+/**
+ * Options that control how Insights events are sent.
+ *
+ * @public
+ */
+export declare interface InsightsApiClientRequestOptions {
+    /**
+     * 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;
+}
+
+/**
+ * Options for {@link createProtectedFetchMethod}, combining timeout and retry behavior.
+ *
+ * @see {@link RetryFetchMethodOptions}
+ * @see {@link TimeoutFetchMethodOptions}
+ *
+ * @public
+ */
+export declare interface ProtectedFetchMethodOptions extends RetryFetchMethodOptions, TimeoutFetchMethodOptions {
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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 { }