@contentful/optimization-api-client 0.1.0-alpha

package/dist/builders/EventBuilder.js

@@ -0,0 +1,349 @@
+import { Campaign, GeoLocation, Page, PageEventContext, Properties, Screen, ScreenEventContext, Traits, } from '@contentful/optimization-api-schemas';
+import { merge } from 'es-toolkit';
+import * as z from 'zod/mini';
+const UniversalEventBuilderArgs = z.object({
+    campaign: z.optional(Campaign),
+    locale: z.optional(z.string()),
+    location: z.optional(GeoLocation),
+    page: z.optional(Page),
+    screen: z.optional(Screen),
+    userAgent: z.optional(z.string()),
+});
+const ComponentViewBuilderArgs = z.extend(UniversalEventBuilderArgs, {
+    componentId: z.string(),
+    experienceId: z.optional(z.string()),
+    variantIndex: z.optional(z.number()),
+    sticky: z.optional(z.boolean()),
+});
+const IdentifyBuilderArgs = z.extend(UniversalEventBuilderArgs, {
+    traits: z.optional(Traits),
+    userId: z.string(),
+});
+const PageViewBuilderArgs = z.extend(UniversalEventBuilderArgs, {
+    properties: z.optional(z.partial(Page)),
+});
+const ScreenViewBuilderArgs = z.extend(UniversalEventBuilderArgs, {
+    name: z.string(),
+    properties: Properties,
+});
+const TrackBuilderArgs = z.extend(UniversalEventBuilderArgs, {
+    event: z.string(),
+    properties: z.optional(z.prefault(Properties, {})),
+});
+/**
+ * Default page properties used when no explicit page information is available.
+ *
+ * @public
+ *
+ * @defaultValue
+ * ```ts
+ * {
+ *   path: '',
+ *   query: {},
+ *   referrer: '',
+ *   search: '',
+ *   title: '',
+ *   url: '',
+ * }
+ * ```
+ *
+ * @remarks
+ * Values are required by the API; values may not be `undefined`. Empty values are valid.
+ */
+export const DEFAULT_PAGE_PROPERTIES = {
+    path: '',
+    query: {},
+    referrer: '',
+    search: '',
+    title: '',
+    url: '',
+};
+/**
+ * Internal helper class for building analytics and personalization events.
+ *
+ * @remarks
+ * This class coordinates configuration and argument validation to produce
+ * strongly-typed event payloads compatible with
+ * `@contentful/optimization-api-schemas`.
+ *
+ * @public
+ */
+class EventBuilder {
+    /**
+     * Application metadata attached to each event.
+     *
+     * @internal
+     */
+    app;
+    /**
+     * Channel value attached to each event.
+     *
+     * @internal
+     */
+    channel;
+    /**
+     * Library metadata attached to each event.
+     *
+     * @internal
+     */
+    library;
+    /**
+     * Function that provides the locale when available.
+     *
+     * @internal
+     */
+    getLocale;
+    /**
+     * Function that provides baseline page properties.
+     *
+     * @internal
+     */
+    getPageProperties;
+    /**
+     * Function that provides the user agent string when available.
+     *
+     * @internal
+     */
+    getUserAgent;
+    /**
+     * Creates a new {@link EventBuilder} instance.
+     *
+     * @param config - Configuration used to customize event payloads.
+     *
+     * @internal
+     * @remarks
+     * Callers are expected to reuse a single instance when possible to avoid
+     * repeatedly reconfiguring the builder.
+     *
+     * @example
+     * ```ts
+     * const builder = new EventBuilder({
+     *   channel: 'web',
+     *   library: { name: '@contentful/optimization-sdk', version: '1.0.0' },
+     * })
+     * ```
+     */
+    constructor(config) {
+        const { app, channel, library, getLocale, getPageProperties, getUserAgent } = config;
+        this.app = app;
+        this.channel = channel;
+        this.library = library;
+        this.getLocale = getLocale ?? (() => 'en-US');
+        this.getPageProperties = getPageProperties ?? (() => DEFAULT_PAGE_PROPERTIES);
+        this.getUserAgent = getUserAgent ?? (() => undefined);
+    }
+    /**
+     * Builds the universal event properties shared across all event types.
+     *
+     * @param args - Arguments overriding the default context values.
+     * @returns A fully populated {@link UniversalEventProperties} object.
+     *
+     * @protected
+     *
+     * @remarks
+     * This method is used internally by the specific event-builder methods
+     * (e.g. {@link EventBuilder.buildPageView}).
+     */
+    buildUniversalEventProperties({ campaign = {}, locale, location, page, screen, userAgent, }) {
+        const timestamp = new Date().toISOString();
+        return {
+            channel: this.channel,
+            context: {
+                app: this.app,
+                campaign,
+                gdpr: { isConsentGiven: true },
+                library: this.library,
+                locale: locale ?? this.getLocale() ?? 'en-US',
+                location,
+                page: page ?? this.getPageProperties(),
+                screen,
+                userAgent: userAgent ?? this.getUserAgent(),
+            },
+            messageId: crypto.randomUUID(),
+            originalTimestamp: timestamp,
+            sentAt: timestamp,
+            timestamp,
+        };
+    }
+    /**
+     * Builds a component view event payload for a Contentful entry-based component.
+     *
+     * @param args - {@link ComponentViewBuilderArgs} arguments describing the component view.
+     * @returns A {@link ComponentViewEvent} describing the view.
+     *
+     * @public
+     *
+     * @example
+     * ```ts
+     * const event = builder.buildComponentView({
+     *   componentId: 'entry-123',
+     *   experienceId: 'personalization-123',
+     *   variantIndex: 1,
+     * })
+     * ```
+     */
+    buildComponentView(args) {
+        const { componentId, experienceId, variantIndex, ...universal } = ComponentViewBuilderArgs.parse(args);
+        return {
+            ...this.buildUniversalEventProperties(universal),
+            type: 'component',
+            componentType: 'Entry',
+            componentId,
+            experienceId,
+            variantIndex: variantIndex ?? 0,
+        };
+    }
+    /**
+     * Builds a component view event payload for a Custom Flag component.
+     *
+     * @param args - {@link ComponentViewBuilderArgs} arguments describing the Custom Flag view.
+     * @returns A {@link ComponentViewEvent} describing the view.
+     *
+     * @public
+     *
+     * @remarks
+     * This is a specialized variant of {@link EventBuilder.buildComponentView}
+     * that sets `componentType` to `'Variable'`.
+     *
+     * @example
+     * ```ts
+     * const event = builder.buildFlagView({
+     *   componentId: 'feature-flag-key',
+     *   experienceId: 'personalization-123',
+     * })
+     * ```
+     */
+    buildFlagView(args) {
+        return {
+            ...this.buildComponentView(args),
+            componentType: 'Variable',
+        };
+    }
+    /**
+     * Builds an identify event payload to associate a user ID with traits.
+     *
+     * @param args - {@link IdentifyBuilderArgs} arguments describing the identified user.
+     * @returns An {@link IdentifyEvent} payload.
+     *
+     * @public
+     *
+     * @remarks
+     * - Traits are merged by the API; only specified properties may be overwritten.
+     * - The User ID is consumer-specified and should not contain the value of any
+     *   ID generated by the Experience API.
+     *
+     * @example
+     * ```ts
+     * const event = builder.buildIdentify({
+     *   userId: 'user-123',
+     *   traits: { plan: 'pro' },
+     * })
+     * ```
+     */
+    buildIdentify(args) {
+        const { traits = {}, userId, ...universal } = IdentifyBuilderArgs.parse(args);
+        return {
+            ...this.buildUniversalEventProperties(universal),
+            type: 'identify',
+            traits,
+            userId,
+        };
+    }
+    /**
+     * Builds a page view event payload.
+     *
+     * @param args - Optional {@link PageViewBuilderArgs} overrides for the page view event.
+     * @returns A {@link PageViewEvent} payload.
+     *
+     * @public
+     *
+     * @remarks
+     * Page properties are created by merging:
+     * 1. The base page properties from {@link EventBuilderConfig.getPageProperties}, and
+     * 2. The partial `properties` argument passed in.
+     *
+     * The title always falls back to {@link DEFAULT_PAGE_PROPERTIES}.title when undefined.
+     *
+     * @example
+     * ```ts
+     * const event = builder.buildPageView({
+     *   properties: {
+     *     title: 'Homepage',
+     *   },
+     * })
+     * ```
+     */
+    buildPageView(args = {}) {
+        const { properties = {}, ...universal } = PageViewBuilderArgs.parse(args);
+        const pageProperties = this.getPageProperties();
+        const merged = merge({
+            ...pageProperties,
+            title: pageProperties.title ?? DEFAULT_PAGE_PROPERTIES.title,
+        }, properties);
+        const { context: { screen: _, ...universalContext }, ...universalProperties } = this.buildUniversalEventProperties(universal);
+        const context = PageEventContext.parse(universalContext);
+        return {
+            ...universalProperties,
+            context,
+            type: 'page',
+            properties: merged,
+        };
+    }
+    /**
+     * Builds a screen view event payload.
+     *
+     * @param args - {@link ScreenViewBuilderArgs} arguments for the screen view event.
+     * @returns A {@link ScreenViewEvent} payload.
+     *
+     * @public
+     *
+     * @example
+     * ```ts
+     * const event = builder.buildScreenView({
+     *   name: 'home',
+     *   properties: {
+     *     title: 'Home Screen',
+     *   },
+     * })
+     * ```
+     */
+    buildScreenView(args) {
+        const { name, properties, ...universal } = ScreenViewBuilderArgs.parse(args);
+        const { context: { page: _, ...universalContext }, ...universalProperties } = this.buildUniversalEventProperties(universal);
+        const context = ScreenEventContext.parse(universalContext);
+        return {
+            ...universalProperties,
+            context,
+            type: 'screen',
+            name,
+            properties,
+        };
+    }
+    /**
+     * Builds a track event payload for arbitrary user actions.
+     *
+     * @param args - {@link TrackBuilderArgs} arguments describing the tracked event.
+     * @returns A {@link TrackEvent} payload.
+     *
+     * @public
+     *
+     * @example
+     * ```ts
+     * const event = builder.buildTrack({
+     *   event: 'button_clicked',
+     *   properties: { id: 'primary-cta', location: 'hero' },
+     * })
+     * ```
+     */
+    buildTrack(args) {
+        const { event, properties = {}, ...universal } = TrackBuilderArgs.parse(args);
+        return {
+            ...this.buildUniversalEventProperties(universal),
+            type: 'track',
+            event,
+            properties,
+        };
+    }
+}
+export default EventBuilder;
+//# sourceMappingURL=EventBuilder.js.map

package/dist/builders/EventBuilder.js.map

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

package/dist/builders/index.d.ts

@@ -0,0 +1,3 @@
+export * from './EventBuilder';
+export { default as EventBuilder } from './EventBuilder';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/builders/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA;AAE9B,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/builders/index.js

@@ -0,0 +1,3 @@
+export * from './EventBuilder';
+export { default as EventBuilder } from './EventBuilder';
+//# sourceMappingURL=index.js.map

package/dist/builders/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/builders/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA;AAE9B,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/experience/ExperienceApiClient.d.ts

@@ -0,0 +1,267 @@
+import { ExperienceEventArray, type BatchExperienceData, type BatchExperienceEventArray, type OptimizationData } from '@contentful/optimization-api-schemas';
+import ApiClientBase, { type ApiConfig } from '../ApiClientBase';
+/**
+ * Default base URL for the Experience API.
+ *
+ * @public
+ */
+export declare const EXPERIENCE_BASE_URL = "https://experience.ninetailed.co/";
+/**
+ * Feature flags supported by the Experience API.
+ */
+type Feature = 'ip-enrichment' | 'location';
+/**
+ * Options that control how requests to the Experience API are handled.
+ */
+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;
+}
+/**
+ * Parameters used when creating a profile.
+ */
+interface CreateProfileParams {
+    /**
+     * Events used to aggregate the profile state.
+     */
+    events: ExperienceEventArray;
+}
+/**
+ * Parameters used when updating an existing profile.
+ */
+interface UpdateProfileParams extends CreateProfileParams {
+    /**
+     * ID of the profile to update.
+     */
+    profileId: string;
+}
+/**
+ * Parameters used when creating or updating a profile.
+ */
+interface UpsertProfileParams extends CreateProfileParams {
+    /**
+     * Optional ID of the profile; when omitted, a new profile is created.
+     */
+    profileId?: string;
+}
+/**
+ * Parameters used when performing a batch profile update.
+ */
+interface BatchUpdateProfileParams {
+    /**
+     * Batch of events to process.
+     */
+    events: BatchExperienceEventArray;
+}
+/**
+ * Configuration for {@link ExperienceApiClient}.
+ */
+export interface ExperienceApiClientConfig extends ApiConfig, RequestOptions {
+}
+/**
+ * Client for interacting with the Experience API.
+ *
+ * @public
+ *
+ * @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')
+ * ```
+ */
+export default class ExperienceApiClient extends ApiClientBase {
+    /**
+     * Base URL used for Experience API requests.
+     */
+    protected readonly baseUrl: string;
+    private readonly enabledFeatures?;
+    private readonly ip?;
+    private readonly locale?;
+    private readonly plainText?;
+    private readonly preflight?;
+    /**
+     * Creates a new {@link ExperienceApiClient} instance.
+     *
+     * @param config - Configuration for the Experience API client.
+     */
+    constructor(config: ExperienceApiClientConfig);
+    /**
+     * Retrieves a profile by ID.
+     *
+     * @param id - The profile ID to retrieve.
+     * @param options - Optional request options. `preflight` and `plainText` are not allowed here.
+     * @returns The current optimization data for the profile.
+     *
+     * @throws {@link Error}
+     * Thrown if `id` is missing or the underlying request fails.
+     *
+     * @example
+     * ```ts
+     * const profile = await client.getProfile('profile-id', {
+     *   locale: 'en-US',
+     * })
+     * ```
+     */
+    getProfile(id: string, options?: Omit<RequestOptions, 'preflight' | 'plainText'>): Promise<OptimizationData>;
+    /**
+     * Sends a POST request to mutate a profile or profiles.
+     *
+     * @param request - Mutation request options including URL, body, and request options.
+     * @returns The raw {@link Response} from the underlying fetch.
+     *
+     * @internal
+     */
+    private makeProfileMutationRequest;
+    /**
+     * Creates a profile and returns the resulting optimization data.
+     *
+     * @param params - Parameters containing the events to aggregate into the profile.
+     * @param options - Optional request options.
+     * @returns The optimization data for the newly created profile.
+     *
+     * @remarks
+     * The returned profile ID can be used for subsequent update requests.
+     *
+     * @example
+     * ```ts
+     * const data = await client.createProfile({
+     *   events: [{ type: 'identify', userId: 'user-123' }],
+     * })
+     * ```
+     */
+    createProfile({ events }: CreateProfileParams, options?: RequestOptions): Promise<OptimizationData>;
+    /**
+     * Updates an existing profile with the given profile ID.
+     *
+     * @param params - Parameters including the profile ID and events.
+     * @param options - Optional request options.
+     * @returns The updated optimization data for the profile.
+     *
+     * @throws {@link Error}
+     * Thrown if `profileId` is missing or the underlying request fails.
+     *
+     * @example
+     * ```ts
+     * const data = await client.updateProfile({
+     *   profileId: 'profile-id',
+     *   events: [{ type: 'track', event: 'viewed_video' }],
+     * })
+     * ```
+     */
+    updateProfile({ profileId, events }: UpdateProfileParams, options?: RequestOptions): Promise<OptimizationData>;
+    /**
+     * Creates or updates a profile depending on whether a `profileId` is provided.
+     *
+     * @param params - Parameters including optional profile ID and events.
+     * @param options - Optional request options.
+     * @returns The resulting optimization data.
+     *
+     * @example
+     * ```ts
+     * // Create
+     * await client.upsertProfile({ events })
+     *
+     * // Update
+     * await client.upsertProfile({ profileId: 'profile-id', events })
+     * ```
+     */
+    upsertProfile({ profileId, events }: UpsertProfileParams, options?: RequestOptions): Promise<OptimizationData>;
+    /**
+     * Sends multiple events to the Ninetailed Experience API to upsert many profiles.
+     *
+     * @param params - Parameters containing the batch of events.
+     * @param options - Optional request options.
+     * @returns The list of profiles affected by the batch operation.
+     *
+     * @remarks
+     * 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;
+}
+export {};
+//# sourceMappingURL=ExperienceApiClient.d.ts.map

package/dist/experience/ExperienceApiClient.d.ts.map

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