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

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <a href="https://www.contentful.com/developers/docs/personalization/">
-    <img alt="Contentful Logo" title="Contentful" src="../../contentful-icon.png" width="150">
+    <img alt="Contentful Logo" title="Contentful" src="https://raw.githubusercontent.com/contentful/optimization/v0.1.0-alpha11/contentful-icon.png" width="150">
   </a>
 </p>
 
@@ -10,8 +10,8 @@
 
 <div align="center">
 
-[Readme](./README.md) · [Reference](https://contentful.github.io/optimization) ·
-[Contributing](../../CONTRIBUTING.md)
+[Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](https://github.com/contentful/optimization/blob/v0.1.0-alpha11/CONTRIBUTING.md)
 
 </div>
 
@@ -20,11 +20,12 @@
 > The Optimization SDK Suite is pre-release (alpha). Breaking changes may be published at any time.
 
 The Contentful Optimization API Client Library provides methods for interfacing with Contentful's
-Experience and Insights APIs, which serve its Personalization and Analytics products.
+Experience API and Insights API, which serve its Personalization and Analytics products.
 
 > [!NOTE]
 >
-> In the future, the Experience and Insights APIs may be combined behind an Optimization API
+> The Experience API and Insights API are separate today, and this client provides a unified SDK
+> surface for both APIs.
 
 <details>
   <summary>Table of Contents</summary>
@@ -34,8 +35,8 @@ Experience and Insights APIs, which serve its Personalization and Analytics prod
 - [Configuration](#configuration)
   - [Top-level Configuration Options](#top-level-configuration-options)
   - [Fetch Options](#fetch-options)
-  - [Analytics Options](#analytics-options)
-  - [Personalization Options](#personalization-options)
+  - [Insights API Options](#insights-api-options)
+  - [Experience API Options](#experience-api-options)
 - [Working With the APIs](#working-with-the-apis)
   - [Experience API](#experience-api)
     - [Get Profile data](#get-profile-data)
@@ -45,9 +46,7 @@ Experience and Insights APIs, which serve its Personalization and Analytics prod
     - [Upsert Many Profiles](#upsert-many-profiles)
   - [Insights API](#insights-api)
     - [Send Batch Events](#send-batch-events)
-- [Event Builder](#event-builder)
-  - [Event Builder Configuration](#event-builder-configuration)
-    - [Event Builder Configured Methods](#event-builder-configured-methods)
+- [Event Construction](#event-construction)
 
 <!-- mtoc-end -->
 </details>
@@ -76,20 +75,20 @@ const client = new ApiClient({ clientId: 'abc123' })
 
 ### Top-level Configuration Options
 
-| Option            | Required? | Default                       | Description                                                  |
-| ----------------- | --------- | ----------------------------- | ------------------------------------------------------------ |
-| `analytics`       | No        | See "Analytics Options"       | Configuration specific to the Analytics/Insights API         |
-| `clientId`        | Yes       | N/A                           | The Optimization API key                                     |
-| `environment`     | No        | `'main'`                      | The environment identifier                                   |
-| `fetchOptions`    | No        | See "Fetch Options"           | Configuration for Fetch timeout and retry functionality      |
-| `personalization` | No        | See "Personalization Options" | Configuration specific to the Personalization/Experience API |
+| Option         | Required? | Default                      | Description                                                 |
+| -------------- | --------- | ---------------------------- | ----------------------------------------------------------- |
+| `experience`   | No        | See "Experience API Options" | Configuration specific to the Experience API                |
+| `clientId`     | Yes       | N/A                          | Shared API key for Experience API and Insights API requests |
+| `environment`  | No        | `'main'`                     | The environment identifier                                  |
+| `fetchOptions` | No        | See "Fetch Options"          | Configuration for Fetch timeout and retry functionality     |
+| `insights`     | No        | See "Insights API Options"   | Configuration specific to the Insights API                  |
 
 ### Fetch Options
 
 Fetch options allow for configuration of both a Fetch API-compatible fetch method and the
-retry/timeout logic integrated into the Optimization API Client. Specify the `fetchMethod` when the
-host application environment does not offer a `fetch` method that is compatible with the standard
-Fetch API in its global scope.
+retry/timeout logic integrated into this API client. Specify the `fetchMethod` when the host
+application environment does not offer a `fetch` method that is compatible with the standard Fetch
+API in its global scope.
 
 | Option             | Required? | Default     | Description                                                           |
 | ------------------ | --------- | ----------- | --------------------------------------------------------------------- |
@@ -108,13 +107,13 @@ Configuration method signatures:
 > [!NOTE]
 >
 > Retry behavior is intentionally fixed to HTTP `503` responses (`Service Unavailable`) for the
-> default SDK transport policy. This matches current Experience and Insights API expectations: `503`
-> is treated as the transient availability signal, while other response classes are handled by
+> default SDK transport policy. This matches current Experience API and Insights API expectations:
+> `503` is treated as the transient availability signal, while other response classes are handled by
 > caller logic and are intentionally not retried by default. Treat this as deliberate contract
 > behavior, not a transport gap; broaden retry status handling only with an explicit API contract
 > change.
 
-### Analytics Options
+### Insights API Options
 
 | Option          | Required? | Default                                    | Description                                                              |
 | --------------- | --------- | ------------------------------------------ | ------------------------------------------------------------------------ |
@@ -125,7 +124,7 @@ Configuration method signatures:
 
 - `beaconHandler`: `(url: string | URL, data: BatchInsightsEventArray) => boolean`
 
-### Personalization Options
+### Experience API Options
 
 | Option            | Required? | Default                               | Description                                                         |
 | ----------------- | --------- | ------------------------------------- | ------------------------------------------------------------------- |
@@ -144,7 +143,7 @@ Configuration method signatures:
 
 ### Experience API
 
-Experience API methods are scoped to the client's `experience` member. All singular experience
+Experience API methods are scoped to the client's `experience` member. All singular Experience API
 methods return a `Promise` that resolves with the following data:
 
 ```json
@@ -152,14 +151,14 @@ methods return a `Promise` that resolves with the following data:
   "profile": {
     /* User profile data */
   },
-  "personalizations": [
+  "selectedOptimizations": [
     {
-      /* Personalization/experience configuration for the associated profile */
+      /* Optimization/Experience API configuration for the associated profile */
     }
   ],
   "changes": [
     {
-      /* Similar to `personalizations` but currently used for Custom Flags */
+      /* Custom Flag changes associated with the evaluated profile */
     }
   ]
 }
@@ -218,7 +217,7 @@ const profiles = await client.experience.upsertManyProfiles(
     events: [
       {
         anonymousId: 'anon-123',
-        // valid Experience event payload fields
+        // valid Experience API event payload fields
       },
     ],
   },
@@ -251,63 +250,8 @@ await client.insights.sendBatchEvents([
 ])
 ```
 
-## Event Builder
+## Event Construction
 
-The Event Builder is a helper class that assists in constructing valid events for submission to the
-Experience and Insights APIs.
-
-### Event Builder Configuration
-
-Event Builder configuration options assist in adding contextual data to each event created by a
-builder instance.
-
-| Option              | Required? | Default                         | Description                                                                        |
-| ------------------- | --------- | ------------------------------- | ---------------------------------------------------------------------------------- |
-| `app`               | No        | `undefined`                     | The application definition used to attribute events to a specific consumer app     |
-| `channel`           | Yes       | N/A                             | The channel that identifies where events originate from (e.g. `'web'`, `'mobile'`) |
-| `library`           | Yes       | N/A                             | The client library metadata that is attached to all events                         |
-| `getLocale`         | No        | `() => 'en-US'`                 | Function used to resolve the locale for outgoing events                            |
-| `getPageProperties` | No        | `() => DEFAULT_PAGE_PROPERTIES` | Function that returns the current page properties                                  |
-| `getUserAgent`      | No        | `() => undefined`               | Function used to obtain the current user agent string when applicable              |
-
-The `get*` functions are most useful in stateful environments. Stateless environments should set the
-related data directly via Event Builder method arguments.
-
-The `channel` option may contain one of the following values:
-
-- `web`
-- `mobile`
-- `server`
-
-Configuration method signatures:
-
-- `getLocale`: `() => string | undefined`
-- `getPageProperties`:
-
-  ```ts
-  () => {
-    path: string,
-    query: Record<string, string>,
-    referrer: string,
-    search: string,
-    title?: string,
-    url: string
-  }
-  ```
-
-- `getUserAgent`: `() => string | undefined`
-
-#### Event Builder Configured Methods
-
-- `buildComponentClick`: Builds a component click event payload for a Contentful entry-based
-  component
-- `buildComponentView`: Builds a component view event payload for a Contentful entry-based component
-- `buildFlagView`: Builds a component view payload event for a Custom Flag component
-- `buildIdentify`: Builds an identify event payload to associate a user ID with traits
-- `buildPageView`: Builds a page view event payload
-- `buildScreenView`: Builds a screen view event payload
-- `buildTrack`: Builds a track event payload for arbitrary user actions
-
-See the
-[Event Builder documentation](https://contentful.github.io/optimization/classes/_contentful_optimization-api-client.EventBuilder.html)
-for more information regarding arguments and return values.
+Event-construction helpers (`EventBuilder`) are part of
+[`@contentful/optimization-core`](https://github.com/contentful/optimization/blob/v0.1.0-alpha11/packages/universal/core-sdk/README.md) and environment SDKs that build on top of
+it. This package focuses on API transport and request/response validation.

package/dist/index.cjs

@@ -148,11 +148,14 @@ var __webpack_exports__ = {};
 (()=>{
     __webpack_require__.r(__webpack_exports__);
     __webpack_require__.d(__webpack_exports__, {
+        createTimeoutFetchMethod: ()=>createTimeoutFetchMethod,
+        ExperienceApiClient: ()=>ExperienceApiClient,
+        createProtectedFetchMethod: ()=>createProtectedFetchMethod,
         EXPERIENCE_BASE_URL: ()=>EXPERIENCE_BASE_URL,
         ApiClient: ()=>ApiClient,
         INSIGHTS_BASE_URL: ()=>INSIGHTS_BASE_URL,
-        DEFAULT_PAGE_PROPERTIES: ()=>DEFAULT_PAGE_PROPERTIES,
-        EventBuilder: ()=>builders_EventBuilder
+        createRetryFetchMethod: ()=>createRetryFetchMethod,
+        InsightsApiClient: ()=>InsightsApiClient
     });
     const optimization_api_schemas_namespaceObject = require("@contentful/optimization-api-schemas");
     var logger = __webpack_require__("./src/logger.ts");
@@ -319,7 +322,7 @@ var __webpack_exports__ = {};
                 const { data: { changes, experiences, profile } } = (0, optimization_api_schemas_namespaceObject.parseWithFriendlyError)(optimization_api_schemas_namespaceObject.ExperienceResponse, await response.json());
                 const data = {
                     changes,
-                    personalizations: experiences,
+                    selectedOptimizations: experiences,
                     profile
                 };
                 ExperienceApiClient_logger.debug(`"${requestName}" request successfully completed`);
@@ -353,7 +356,7 @@ var __webpack_exports__ = {};
                 const { data: { changes, experiences, profile } } = (0, optimization_api_schemas_namespaceObject.parseWithFriendlyError)(optimization_api_schemas_namespaceObject.ExperienceResponse, await response.json());
                 const data = {
                     changes,
-                    personalizations: experiences,
+                    selectedOptimizations: experiences,
                     profile
                 };
                 ExperienceApiClient_logger.debug(`"${requestName}" request successfully completed`);
@@ -380,7 +383,7 @@ var __webpack_exports__ = {};
                 const { data: { changes, experiences, profile } } = (0, optimization_api_schemas_namespaceObject.parseWithFriendlyError)(optimization_api_schemas_namespaceObject.ExperienceResponse, await response.json());
                 const data = {
                     changes,
-                    personalizations: experiences,
+                    selectedOptimizations: experiences,
                     profile
                 };
                 ExperienceApiClient_logger.debug(`"${requestName}" request successfully completed`);
@@ -459,7 +462,6 @@ var __webpack_exports__ = {};
             });
         }
     }
-    const experience = ExperienceApiClient;
     const InsightsApiClient_logger = (0, logger.createScopedLogger)('ApiClient:Insights');
     const INSIGHTS_BASE_URL = 'https://ingest.insights.ninetailed.co/';
     class InsightsApiClient extends src_ApiClientBase {
@@ -503,216 +505,46 @@ var __webpack_exports__ = {};
             }
         }
     }
-    const insights = InsightsApiClient;
     class ApiClient {
         config;
         experience;
         insights;
         constructor(config){
-            const { personalization, analytics, clientId, environment, fetchOptions } = config;
+            const { experience, insights, clientId, environment, fetchOptions } = config;
             const apiConfig = {
                 clientId,
                 environment,
                 fetchOptions
             };
             this.config = apiConfig;
-            this.experience = new experience({
+            this.experience = new ExperienceApiClient({
                 ...apiConfig,
-                ...personalization
+                ...experience
             });
-            this.insights = new insights({
+            this.insights = new InsightsApiClient({
                 ...apiConfig,
-                ...analytics
+                ...insights
             });
         }
     }
-    const object_namespaceObject = require("es-toolkit/object");
-    const mini_namespaceObject = require("zod/mini");
-    const UniversalEventBuilderArgs = mini_namespaceObject.object({
-        campaign: mini_namespaceObject.optional(optimization_api_schemas_namespaceObject.Campaign),
-        locale: mini_namespaceObject.optional(mini_namespaceObject.string()),
-        location: mini_namespaceObject.optional(optimization_api_schemas_namespaceObject.GeoLocation),
-        page: mini_namespaceObject.optional(optimization_api_schemas_namespaceObject.Page),
-        screen: mini_namespaceObject.optional(optimization_api_schemas_namespaceObject.Screen),
-        userAgent: mini_namespaceObject.optional(mini_namespaceObject.string())
-    });
-    const ComponentInteractionBuilderArgsBase = mini_namespaceObject.extend(UniversalEventBuilderArgs, {
-        componentId: mini_namespaceObject.string(),
-        experienceId: mini_namespaceObject.optional(mini_namespaceObject.string()),
-        variantIndex: mini_namespaceObject.optional(mini_namespaceObject.number())
-    });
-    const ComponentViewBuilderArgs = mini_namespaceObject.extend(ComponentInteractionBuilderArgsBase, {
-        sticky: mini_namespaceObject.optional(mini_namespaceObject.boolean()),
-        componentViewId: mini_namespaceObject.string(),
-        viewDurationMs: mini_namespaceObject.number()
-    });
-    const ComponentClickBuilderArgs = ComponentInteractionBuilderArgsBase;
-    const ComponentHoverBuilderArgs = mini_namespaceObject.extend(ComponentInteractionBuilderArgsBase, {
-        componentHoverId: mini_namespaceObject.string(),
-        hoverDurationMs: mini_namespaceObject.number()
-    });
-    const IdentifyBuilderArgs = mini_namespaceObject.extend(UniversalEventBuilderArgs, {
-        traits: mini_namespaceObject.optional(optimization_api_schemas_namespaceObject.Traits),
-        userId: mini_namespaceObject.string()
-    });
-    const PageViewBuilderArgs = mini_namespaceObject.extend(UniversalEventBuilderArgs, {
-        properties: mini_namespaceObject.optional(mini_namespaceObject.partial(optimization_api_schemas_namespaceObject.Page))
-    });
-    const ScreenViewBuilderArgs = mini_namespaceObject.extend(UniversalEventBuilderArgs, {
-        name: mini_namespaceObject.string(),
-        properties: optimization_api_schemas_namespaceObject.Properties
-    });
-    const TrackBuilderArgs = mini_namespaceObject.extend(UniversalEventBuilderArgs, {
-        event: mini_namespaceObject.string(),
-        properties: mini_namespaceObject.optional(mini_namespaceObject.prefault(optimization_api_schemas_namespaceObject.Properties, {}))
-    });
-    const DEFAULT_PAGE_PROPERTIES = {
-        path: '',
-        query: {},
-        referrer: '',
-        search: '',
-        title: '',
-        url: ''
-    };
-    class EventBuilder {
-        app;
-        channel;
-        library;
-        getLocale;
-        getPageProperties;
-        getUserAgent;
-        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 ?? (()=>void 0);
-        }
-        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
-            };
-        }
-        buildEntryComponentBase(universal, componentId, experienceId, variantIndex) {
-            return {
-                ...this.buildUniversalEventProperties(universal),
-                componentType: 'Entry',
-                componentId,
-                experienceId,
-                variantIndex: variantIndex ?? 0
-            };
-        }
-        buildComponentView(args) {
-            const { componentId, componentViewId, experienceId, variantIndex, viewDurationMs, ...universal } = (0, optimization_api_schemas_namespaceObject.parseWithFriendlyError)(ComponentViewBuilderArgs, args);
-            return {
-                ...this.buildEntryComponentBase(universal, componentId, experienceId, variantIndex),
-                type: 'component',
-                componentViewId,
-                viewDurationMs
-            };
-        }
-        buildComponentClick(args) {
-            const { componentId, experienceId, variantIndex, ...universal } = (0, optimization_api_schemas_namespaceObject.parseWithFriendlyError)(ComponentClickBuilderArgs, args);
-            return {
-                ...this.buildEntryComponentBase(universal, componentId, experienceId, variantIndex),
-                type: 'component_click'
-            };
-        }
-        buildComponentHover(args) {
-            const { componentHoverId, componentId, experienceId, hoverDurationMs, variantIndex, ...universal } = (0, optimization_api_schemas_namespaceObject.parseWithFriendlyError)(ComponentHoverBuilderArgs, args);
-            return {
-                ...this.buildEntryComponentBase(universal, componentId, experienceId, variantIndex),
-                type: 'component_hover',
-                componentHoverId,
-                hoverDurationMs
-            };
-        }
-        buildFlagView(args) {
-            return {
-                ...this.buildComponentView(args),
-                componentType: 'Variable'
-            };
-        }
-        buildIdentify(args) {
-            const { traits = {}, userId, ...universal } = (0, optimization_api_schemas_namespaceObject.parseWithFriendlyError)(IdentifyBuilderArgs, args);
-            return {
-                ...this.buildUniversalEventProperties(universal),
-                type: 'identify',
-                traits,
-                userId
-            };
-        }
-        buildPageView(args = {}) {
-            const { properties = {}, ...universal } = (0, optimization_api_schemas_namespaceObject.parseWithFriendlyError)(PageViewBuilderArgs, args);
-            const pageProperties = this.getPageProperties();
-            const merged = (0, object_namespaceObject.merge)({
-                ...pageProperties,
-                title: pageProperties.title ?? DEFAULT_PAGE_PROPERTIES.title
-            }, properties);
-            const { context: { screen: _, ...universalContext }, ...universalProperties } = this.buildUniversalEventProperties(universal);
-            const context = (0, optimization_api_schemas_namespaceObject.parseWithFriendlyError)(optimization_api_schemas_namespaceObject.PageEventContext, universalContext);
-            return {
-                ...universalProperties,
-                context,
-                type: 'page',
-                properties: merged
-            };
-        }
-        buildScreenView(args) {
-            const { name, properties, ...universal } = (0, optimization_api_schemas_namespaceObject.parseWithFriendlyError)(ScreenViewBuilderArgs, args);
-            const { context: { page: _, ...universalContext }, ...universalProperties } = this.buildUniversalEventProperties(universal);
-            const context = (0, optimization_api_schemas_namespaceObject.parseWithFriendlyError)(optimization_api_schemas_namespaceObject.ScreenEventContext, universalContext);
-            return {
-                ...universalProperties,
-                context,
-                type: 'screen',
-                name,
-                properties
-            };
-        }
-        buildTrack(args) {
-            const { event, properties = {}, ...universal } = (0, optimization_api_schemas_namespaceObject.parseWithFriendlyError)(TrackBuilderArgs, args);
-            return {
-                ...this.buildUniversalEventProperties(universal),
-                type: 'track',
-                event,
-                properties
-            };
-        }
-    }
-    const builders_EventBuilder = EventBuilder;
 })();
 exports.ApiClient = __webpack_exports__.ApiClient;
-exports.DEFAULT_PAGE_PROPERTIES = __webpack_exports__.DEFAULT_PAGE_PROPERTIES;
 exports.EXPERIENCE_BASE_URL = __webpack_exports__.EXPERIENCE_BASE_URL;
-exports.EventBuilder = __webpack_exports__.EventBuilder;
+exports.ExperienceApiClient = __webpack_exports__.ExperienceApiClient;
 exports.INSIGHTS_BASE_URL = __webpack_exports__.INSIGHTS_BASE_URL;
+exports.InsightsApiClient = __webpack_exports__.InsightsApiClient;
+exports.createProtectedFetchMethod = __webpack_exports__.createProtectedFetchMethod;
+exports.createRetryFetchMethod = __webpack_exports__.createRetryFetchMethod;
+exports.createTimeoutFetchMethod = __webpack_exports__.createTimeoutFetchMethod;
 for(var __rspack_i in __webpack_exports__)if (-1 === [
     "ApiClient",
-    "DEFAULT_PAGE_PROPERTIES",
     "EXPERIENCE_BASE_URL",
-    "EventBuilder",
-    "INSIGHTS_BASE_URL"
+    "ExperienceApiClient",
+    "INSIGHTS_BASE_URL",
+    "InsightsApiClient",
+    "createProtectedFetchMethod",
+    "createRetryFetchMethod",
+    "createTimeoutFetchMethod"
 ].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
 Object.defineProperty(exports, '__esModule', {
     value: true