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

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/optimization-api-client-v1.0.0/contentful-icon.png" width="150">
   </a>
 </p>
 
@@ -10,45 +10,40 @@
 
 <div align="center">
 
-[Readme](./README.md) · [Reference](https://contentful.github.io/optimization) ·
-[Contributing](/CONTRIBUTING.md)
+[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](https://github.com/contentful/optimization/blob/optimization-api-client-v1.0.0/CONTRIBUTING.md)
 
 </div>
 
-The Contentful Optimization API Client Library provides methods for interfacing with Contentful's
-Experience and Insights APIs, which serve its Personalization and Analytics products.
-
-> [!NOTE]
+> [!WARNING]
 >
-> In the future, the Experience and Insights APIs may be combined behind an Optimization API
+> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time.
+
+The Contentful Optimization API Client provides low-level transport for the Experience API and
+Insights API. Application-facing SDKs compose this package with event builders, state management,
+queueing, and runtime-specific defaults.
+
+We recommend starting applications with Web, React Web, Node, or React Native SDKs. Use this package
+directly when building or maintaining SDK layers, tests, tooling, or first-party integrations that
+need raw API access.
 
 <details>
   <summary>Table of Contents</summary>
 <!-- mtoc-start -->
 
-- [Getting Started](#getting-started)
-- [Configuration](#configuration)
-  - [Top-level Configuration Options](#top-level-configuration-options)
-  - [Fetch Options](#fetch-options)
-  - [Analytics Options](#analytics-options)
-  - [Personalization Options](#personalization-options)
-- [Working With the APIs](#working-with-the-apis)
+- [Getting started](#getting-started)
+- [When to use this package](#when-to-use-this-package)
+- [Common configuration](#common-configuration)
+- [API surface](#api-surface)
   - [Experience API](#experience-api)
-    - [Get Profile data](#get-profile-data)
-    - [Create a New Profile](#create-a-new-profile)
-    - [Update an Existing Profile](#update-an-existing-profile)
-    - [Upsert a Profile](#upsert-a-profile)
-    - [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)
+  - [Fetch helpers](#fetch-helpers)
+- [Related](#related)
 
 <!-- mtoc-end -->
 </details>
 
-## Getting Started
+## Getting started
 
 Install using an NPM-compatible package manager, pnpm for example:
 
@@ -56,227 +51,124 @@ Install using an NPM-compatible package manager, pnpm for example:
 pnpm install @contentful/optimization-api-client
 ```
 
-Import the API client; both CJS and ESM module systems are supported, ESM preferred:
+Import and initialize the unified API client; both CJS and ESM module systems are supported, ESM
+preferred:
 
 ```ts
 import { ApiClient } from '@contentful/optimization-api-client'
-```
 
-Configure and initialize the API Client:
-
-```ts
-const client = new ApiClient({ clientId: 'abc123' })
+const client = new ApiClient({
+  clientId: 'your-client-id',
+  environment: 'main',
+})
 ```
 
-## Configuration
-
-### 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 Ninetailed API Key which can be found in the Ninetailed Admin app |
-| `environment`     | No        | `'main'`                      | The Ninetailed environment configured in the Ninetailed Admin app     |
-| `fetchOptions`    | No        | See "Fetch Options"           | Configuration for Fetch timeout and retry functionality               |
-| `personalization` | No        | See "Personalization Options" | Configuration specific to the Personalization/Experience 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.
-
-| Option             | Required? | Default     | Description                                                           |
-| ------------------ | --------- | ----------- | --------------------------------------------------------------------- |
-| `fetchMethod`      | No        | `undefined` | Signature of a fetch method used by the API clients                   |
-| `intervalTimeout`  | No        | `0`         | Delay (in milliseconds) between retry attempts                        |
-| `onFailedAttempt`  | No        | `undefined` | Callback invoked whenever a retry attempt fails                       |
-| `onRequestTimeout` | No        | `undefined` | Callback invoked when a request exceeds the configured timeout        |
-| `requestTimeout`   | No        | `3000`      | Maximum time (in milliseconds) to wait for a response before aborting |
-| `retries`          | No        | `1`         | Maximum number of retry attempts                                      |
-
-Configuration method signatures:
-
-- `fetchMethod`: `(url: string \| URL, init: RequestInit) => Promise<Response>`
-- `onFailedAttempt` and `onRequestTimeout`: `(options: FetchMethodCallbackOptions) => void`
-
-### Analytics Options
-
-| Option          | Required? | Default                                    | Description                                                              |
-| --------------- | --------- | ------------------------------------------ | ------------------------------------------------------------------------ |
-| `baseUrl`       | No        | `'https://ingest.insights.ninetailed.co/'` | Base URL for the Insights API                                            |
-| `beaconHandler` | No        | `undefined`                                | Handler used to enqueue events via the Beacon API or a similar mechanism |
-
-Configuration method signatures:
-
-- `beaconHandler`: `(url: string | URL, data: BatchInsightsEventArray) => boolean`
-
-### Personalization Options
-
-| Option            | Required? | Default                               | Description                                                         |
-| ----------------- | --------- | ------------------------------------- | ------------------------------------------------------------------- |
-| `baseUrl`         | No        | `'https://experience.ninetailed.co/'` | Base URL for the Experience API                                     |
-| `enabledFeatures` | No        | `['ip-enrichment', 'location']`       | Enabled features which the API may use for each request             |
-| `ip`              | No        | `undefined`                           | IP address to override the API behavior for IP analysis             |
-| `locale`          | No        | `'en-US'` (in API)                    | Locale used to translate `location.city` and `location.country`     |
-| `plainText`       | No        | `false`                               | Sends performance-critical endpoints in plain text                  |
-| `preflight`       | No        | `false`                               | Instructs the API to aggregate a new profile state but not store it |
-
-> [!NOTE]
->
-> All options except `baseUrl` may also be provided on a per-request basis.
-
-## Working With the APIs
+## When to use this package
+
+Use `@contentful/optimization-api-client` when you need direct low-level access to the Experience
+API or Insights API transport surface. Use an application-facing SDK when you need optimization
+state, consent handling, event builders, entry resolution, tracking, or platform defaults.
+
+## Common configuration
+
+| Option         | Required? | Default                      | Description                                                 |
+| -------------- | --------- | ---------------------------- | ----------------------------------------------------------- |
+| `clientId`     | Yes       | N/A                          | Shared API key for Experience API and Insights API requests |
+| `environment`  | No        | `'main'`                     | Contentful environment identifier                           |
+| `experience`   | No        | See Experience options below | Experience API endpoint and default request options         |
+| `insights`     | No        | See Insights options below   | Insights API endpoint options                               |
+| `fetchOptions` | No        | SDK defaults                 | Fetch timeout and retry behavior                            |
+
+Common Experience API options:
+
+| Option            | Required? | Default                               | Description                                     |
+| ----------------- | --------- | ------------------------------------- | ----------------------------------------------- |
+| `baseUrl`         | No        | `'https://experience.ninetailed.co/'` | Base URL for the Experience API                 |
+| `enabledFeatures` | No        | `['ip-enrichment', 'location']`       | Experience API features for mutation requests   |
+| `ip`              | No        | `undefined`                           | IP address override for Experience API analysis |
+| `locale`          | No        | API default                           | Locale query parameter for localized responses  |
+| `plainText`       | No        | Endpoint-specific                     | Sends single-profile mutation endpoints as text |
+| `preflight`       | No        | `false`                               | Aggregates a profile state without storing it   |
+
+Experience mutation request options except `baseUrl` can also be provided per mutation request.
+`getProfile` is a read request and only uses `locale` from per-call options; mutation-only options
+such as `enabledFeatures`, `ip`, `plainText`, and `preflight` do not apply. Single-profile mutation
+requests default to `plainText: true` and send `text/plain` unless overridden. Batch profile updates
+with `upsertManyProfiles` are the JSON-default exception and use `plainText: false` by default.
+`locale` is sent as the Experience API `locale` query parameter and can localize profile fields such
+as `location.city` and `location.country`. Higher-level SDK merge-tag helpers resolve against the
+profile values returned by the Experience API, so applications that render localized Contentful
+entries commonly pass the same locale used for the CDA entry fetch. Pass a valid locale tag; invalid
+locale syntax can fail Experience API request validation. See
+[Locale handling in the Optimization SDK Suite](https://contentful.github.io/optimization/documents/Documentation.Concepts.Locale_handling_in_the_Optimization_SDK_Suite.html)
+for how this request locale relates to Contentful and SDK-resolved locales.
+
+Common Insights API options:
+
+| Option    | Required? | Default                                    | Description                   |
+| --------- | --------- | ------------------------------------------ | ----------------------------- |
+| `baseUrl` | No        | `'https://ingest.insights.ninetailed.co/'` | Base URL for the Insights API |
+
+Common `fetchOptions` are `fetchMethod`, `requestTimeout`, `retries`, `intervalTimeout`,
+`onFailedAttempt`, and `onRequestTimeout`. Default retries intentionally apply only to HTTP `503`
+responses.
+
+For every option, callback payload, request type, and response type, use the generated
+[API Client reference](https://contentful.github.io/optimization/modules/_contentful_optimization-api-client.html).
+
+## API surface
 
 ### Experience API
 
-Experience API methods are scoped to the client's `personalization` member. All singular
-personalization methods return a `Promise` that resolves with the following data:
-
-```json
-{
-  "profile": {
-    /* User profile data */
-  },
-  "personalizations": [
-    {
-      /* Personalization/experience configuration for the associated profile */
-    }
-  ],
-  "changes": [
-    {
-      /* Similar to `personalizations` but currently used for Custom Flags */
-    }
-  ]
-}
-```
-
-#### Get Profile data
-
-```ts
-const client = new ApiClient({ clientId: 'abc123' })
-const { profile } = await client.personalization.getProfile('profile-123', { locale: 'de-DE' })
-```
-
-#### Create a New Profile
-
-```ts
-const client = new ApiClient({ clientId: 'abc123' })
-const { profile } = await client.personalization.createProfile({ events: [...] }, { locale: 'de-DE' })
-```
-
-#### Update an Existing Profile
+Experience API methods are scoped to `client.experience` and return profile and optimization data:
 
 ```ts
-const client = new ApiClient({ clientId: 'abc123' })
-const { profile } = await client.personalization.updateProfile(
+const { profile, selectedOptimizations, changes } = await client.experience.upsertProfile(
   {
-    profileId: 'profile-123',
-    events: [...],
+    profileId: 'profile-id',
+    events: [pageEvent],
   },
-  { locale: 'de-DE' }
-)
-```
-
-#### Upsert a Profile
-
-```ts
-const client = new ApiClient({ clientId: 'abc123' })
-const { profile } = await client.personalization.upsertProfile(
-  {
-    profileId,
-    events: [...],
-  },
-  { locale: 'de-DE' }
-)
-```
-
-#### Upsert Many Profiles
-
-The `upsertManyProfiles` method returns a `Promise` that resolves with an array of user profiles.
-Each event should have an additional `anonymousId` property set to the associated anonymous ID or
-profile ID.
-
-```ts
-const client = new ApiClient({ clientId: 'abc123' })
-const profiles = await client.personalization.upsertManyProfiles(
-  { events: [...]},
   { locale: 'de-DE' },
 )
 ```
 
-### Insights API
+Common methods include `getProfile`, `createProfile`, `updateProfile`, `upsertProfile`, and
+`upsertManyProfiles`.
 
-Insights API methods are scoped to the client's `analytics` member. All analytics methods return a
-`Promise` that resolves to `void` (no value).
+### Insights API
 
-#### Send Batch Events
+Insights API methods are scoped to `client.insights` and send analytics event batches:
 
 ```ts
-const client = new ApiClient({ clientId: 'abc123' })
-await client.analytics.sendBatchEvents([
+await client.insights.sendBatchEvents([
   {
-    profile: { id: 'abc-123', ... },
-    events: [{ type: 'track', ... }],
-  }
+    profile,
+    events: [viewEvent],
+  },
 ])
 ```
 
-## Event Builder
-
-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:
+Insights endpoints do not return response data. For last-chance browser lifecycle delivery, pass a
+per-call `beacon` sender that receives the request URL and already serialized body.
 
-- `getLocale`: `() => string | undefined`
-- `getPageProperties`:
+### Fetch helpers
 
-  ```ts
-  () => {
-    path: string,
-    query: Record<string, string>,
-    referrer: string,
-    search: string,
-    title?: string,
-    url: string
-  }
-  ```
+This package also exports fetch helper functions used by SDK layers:
 
-- `getUserAgent`: `() => string | undefined`
+| Helper                       | Purpose                                                 |
+| ---------------------------- | ------------------------------------------------------- |
+| `createProtectedFetchMethod` | Adds timeout and retry protection around a fetch method |
+| `createRetryFetchMethod`     | Applies retry policy to retryable responses             |
+| `createTimeoutFetchMethod`   | Aborts requests after the configured timeout            |
 
-#### Event Builder Configured Methods
+Use generated reference docs for helper signatures and callback payloads.
 
-- `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
-- `buildTrack`: Builds a track event payload for arbitrary user actions
+## Related
 
-See the
-[Event Builder documentation](../classes/_contentful_optimization-api-client.EventBuilder.html) for
-more information regarding arguments and return values.
+- [API Client generated reference](https://contentful.github.io/optimization/modules/_contentful_optimization-api-client.html) -
+  exported API reference
+- [API Schemas](https://github.com/contentful/optimization/blob/optimization-api-client-v1.0.0/packages/universal/api-schemas/README.md) - runtime validation schemas and inferred API types
+- [Optimization Core SDK](https://github.com/contentful/optimization/blob/optimization-api-client-v1.0.0/packages/universal/core-sdk/README.md) - platform-agnostic SDK layer that composes this
+  client
+- [Choosing the right SDK](https://contentful.github.io/optimization/documents/Documentation.Guides.choosing-the-right-sdk.html) -
+  package selection guidance for application integrations