@contentful/optimization-api-client 0.1.0-alpha9 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +106 -245
- package/THIRD_PARTY_NOTICES.txt +2038 -0
- package/dist/index.cjs +78 -219
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +478 -1259
- package/dist/index.d.mts +478 -1259
- package/dist/index.d.ts +478 -1259
- package/dist/index.mjs +63 -213
- package/dist/index.mjs.map +1 -1
- package/package.json +17 -5
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
<p align="center">
|
|
2
2
|
<a href="https://www.contentful.com/developers/docs/personalization/">
|
|
3
|
-
<img alt="Contentful Logo" title="Contentful" src="
|
|
3
|
+
<img alt="Contentful Logo" title="Contentful" src="https://raw.githubusercontent.com/contentful/optimization/optimization-api-client-v1.0.0/contentful-icon.png" width="150">
|
|
4
4
|
</a>
|
|
5
5
|
</p>
|
|
6
6
|
|
|
@@ -10,49 +10,40 @@
|
|
|
10
10
|
|
|
11
11
|
<div align="center">
|
|
12
12
|
|
|
13
|
-
[
|
|
14
|
-
[Contributing](
|
|
13
|
+
[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
|
|
14
|
+
[Reference](https://contentful.github.io/optimization) · [Contributing](https://github.com/contentful/optimization/blob/optimization-api-client-v1.0.0/CONTRIBUTING.md)
|
|
15
15
|
|
|
16
16
|
</div>
|
|
17
17
|
|
|
18
18
|
> [!WARNING]
|
|
19
19
|
>
|
|
20
|
-
> The Optimization SDK Suite is pre-release (alpha). Breaking changes
|
|
20
|
+
> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time.
|
|
21
21
|
|
|
22
|
-
The Contentful Optimization API Client
|
|
23
|
-
|
|
22
|
+
The Contentful Optimization API Client provides low-level transport for the Experience API and
|
|
23
|
+
Insights API. Application-facing SDKs compose this package with event builders, state management,
|
|
24
|
+
queueing, and runtime-specific defaults.
|
|
24
25
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
26
|
+
We recommend starting applications with Web, React Web, Node, or React Native SDKs. Use this package
|
|
27
|
+
directly when building or maintaining SDK layers, tests, tooling, or first-party integrations that
|
|
28
|
+
need raw API access.
|
|
28
29
|
|
|
29
30
|
<details>
|
|
30
31
|
<summary>Table of Contents</summary>
|
|
31
32
|
<!-- mtoc-start -->
|
|
32
33
|
|
|
33
|
-
- [Getting
|
|
34
|
-
- [
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
- [Analytics Options](#analytics-options)
|
|
38
|
-
- [Personalization Options](#personalization-options)
|
|
39
|
-
- [Working With the APIs](#working-with-the-apis)
|
|
34
|
+
- [Getting started](#getting-started)
|
|
35
|
+
- [When to use this package](#when-to-use-this-package)
|
|
36
|
+
- [Common configuration](#common-configuration)
|
|
37
|
+
- [API surface](#api-surface)
|
|
40
38
|
- [Experience API](#experience-api)
|
|
41
|
-
- [Get Profile data](#get-profile-data)
|
|
42
|
-
- [Create a New Profile](#create-a-new-profile)
|
|
43
|
-
- [Update an Existing Profile](#update-an-existing-profile)
|
|
44
|
-
- [Upsert a Profile](#upsert-a-profile)
|
|
45
|
-
- [Upsert Many Profiles](#upsert-many-profiles)
|
|
46
39
|
- [Insights API](#insights-api)
|
|
47
|
-
|
|
48
|
-
- [
|
|
49
|
-
- [Event Builder Configuration](#event-builder-configuration)
|
|
50
|
-
- [Event Builder Configured Methods](#event-builder-configured-methods)
|
|
40
|
+
- [Fetch helpers](#fetch-helpers)
|
|
41
|
+
- [Related](#related)
|
|
51
42
|
|
|
52
43
|
<!-- mtoc-end -->
|
|
53
44
|
</details>
|
|
54
45
|
|
|
55
|
-
## Getting
|
|
46
|
+
## Getting started
|
|
56
47
|
|
|
57
48
|
Install using an NPM-compatible package manager, pnpm for example:
|
|
58
49
|
|
|
@@ -60,254 +51,124 @@ Install using an NPM-compatible package manager, pnpm for example:
|
|
|
60
51
|
pnpm install @contentful/optimization-api-client
|
|
61
52
|
```
|
|
62
53
|
|
|
63
|
-
Import the API client; both CJS and ESM module systems are supported, ESM
|
|
54
|
+
Import and initialize the unified API client; both CJS and ESM module systems are supported, ESM
|
|
55
|
+
preferred:
|
|
64
56
|
|
|
65
57
|
```ts
|
|
66
58
|
import { ApiClient } from '@contentful/optimization-api-client'
|
|
67
|
-
```
|
|
68
59
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
60
|
+
const client = new ApiClient({
|
|
61
|
+
clientId: 'your-client-id',
|
|
62
|
+
environment: 'main',
|
|
63
|
+
})
|
|
73
64
|
```
|
|
74
65
|
|
|
75
|
-
##
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
|
84
|
-
|
|
|
85
|
-
| `
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
|
95
|
-
|
|
|
96
|
-
| `
|
|
97
|
-
| `
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
| Option | Required? | Default | Description |
|
|
131
|
-
| ----------------- | --------- | ------------------------------------- | ------------------------------------------------------------------- |
|
|
132
|
-
| `baseUrl` | No | `'https://experience.ninetailed.co/'` | Base URL for the Experience API |
|
|
133
|
-
| `enabledFeatures` | No | `['ip-enrichment', 'location']` | Enabled features which the API may use for each request |
|
|
134
|
-
| `ip` | No | `undefined` | IP address to override the API behavior for IP analysis |
|
|
135
|
-
| `locale` | No | `'en-US'` (in API) | Locale used to translate `location.city` and `location.country` |
|
|
136
|
-
| `plainText` | No | `false` | Sends performance-critical endpoints in plain text |
|
|
137
|
-
| `preflight` | No | `false` | Instructs the API to aggregate a new profile state but not store it |
|
|
138
|
-
|
|
139
|
-
> [!NOTE]
|
|
140
|
-
>
|
|
141
|
-
> All options except `baseUrl` may also be provided on a per-request basis.
|
|
142
|
-
|
|
143
|
-
## Working With the APIs
|
|
66
|
+
## When to use this package
|
|
67
|
+
|
|
68
|
+
Use `@contentful/optimization-api-client` when you need direct low-level access to the Experience
|
|
69
|
+
API or Insights API transport surface. Use an application-facing SDK when you need optimization
|
|
70
|
+
state, consent handling, event builders, entry resolution, tracking, or platform defaults.
|
|
71
|
+
|
|
72
|
+
## Common configuration
|
|
73
|
+
|
|
74
|
+
| Option | Required? | Default | Description |
|
|
75
|
+
| -------------- | --------- | ---------------------------- | ----------------------------------------------------------- |
|
|
76
|
+
| `clientId` | Yes | N/A | Shared API key for Experience API and Insights API requests |
|
|
77
|
+
| `environment` | No | `'main'` | Contentful environment identifier |
|
|
78
|
+
| `experience` | No | See Experience options below | Experience API endpoint and default request options |
|
|
79
|
+
| `insights` | No | See Insights options below | Insights API endpoint options |
|
|
80
|
+
| `fetchOptions` | No | SDK defaults | Fetch timeout and retry behavior |
|
|
81
|
+
|
|
82
|
+
Common Experience API options:
|
|
83
|
+
|
|
84
|
+
| Option | Required? | Default | Description |
|
|
85
|
+
| ----------------- | --------- | ------------------------------------- | ----------------------------------------------- |
|
|
86
|
+
| `baseUrl` | No | `'https://experience.ninetailed.co/'` | Base URL for the Experience API |
|
|
87
|
+
| `enabledFeatures` | No | `['ip-enrichment', 'location']` | Experience API features for mutation requests |
|
|
88
|
+
| `ip` | No | `undefined` | IP address override for Experience API analysis |
|
|
89
|
+
| `locale` | No | API default | Locale query parameter for localized responses |
|
|
90
|
+
| `plainText` | No | Endpoint-specific | Sends single-profile mutation endpoints as text |
|
|
91
|
+
| `preflight` | No | `false` | Aggregates a profile state without storing it |
|
|
92
|
+
|
|
93
|
+
Experience mutation request options except `baseUrl` can also be provided per mutation request.
|
|
94
|
+
`getProfile` is a read request and only uses `locale` from per-call options; mutation-only options
|
|
95
|
+
such as `enabledFeatures`, `ip`, `plainText`, and `preflight` do not apply. Single-profile mutation
|
|
96
|
+
requests default to `plainText: true` and send `text/plain` unless overridden. Batch profile updates
|
|
97
|
+
with `upsertManyProfiles` are the JSON-default exception and use `plainText: false` by default.
|
|
98
|
+
`locale` is sent as the Experience API `locale` query parameter and can localize profile fields such
|
|
99
|
+
as `location.city` and `location.country`. Higher-level SDK merge-tag helpers resolve against the
|
|
100
|
+
profile values returned by the Experience API, so applications that render localized Contentful
|
|
101
|
+
entries commonly pass the same locale used for the CDA entry fetch. Pass a valid locale tag; invalid
|
|
102
|
+
locale syntax can fail Experience API request validation. See
|
|
103
|
+
[Locale handling in the Optimization SDK Suite](https://contentful.github.io/optimization/documents/Documentation.Concepts.Locale_handling_in_the_Optimization_SDK_Suite.html)
|
|
104
|
+
for how this request locale relates to Contentful and SDK-resolved locales.
|
|
105
|
+
|
|
106
|
+
Common Insights API options:
|
|
107
|
+
|
|
108
|
+
| Option | Required? | Default | Description |
|
|
109
|
+
| --------- | --------- | ------------------------------------------ | ----------------------------- |
|
|
110
|
+
| `baseUrl` | No | `'https://ingest.insights.ninetailed.co/'` | Base URL for the Insights API |
|
|
111
|
+
|
|
112
|
+
Common `fetchOptions` are `fetchMethod`, `requestTimeout`, `retries`, `intervalTimeout`,
|
|
113
|
+
`onFailedAttempt`, and `onRequestTimeout`. Default retries intentionally apply only to HTTP `503`
|
|
114
|
+
responses.
|
|
115
|
+
|
|
116
|
+
For every option, callback payload, request type, and response type, use the generated
|
|
117
|
+
[API Client reference](https://contentful.github.io/optimization/modules/_contentful_optimization-api-client.html).
|
|
118
|
+
|
|
119
|
+
## API surface
|
|
144
120
|
|
|
145
121
|
### Experience API
|
|
146
122
|
|
|
147
|
-
Experience API methods are scoped to
|
|
148
|
-
methods return a `Promise` that resolves with the following data:
|
|
149
|
-
|
|
150
|
-
```json
|
|
151
|
-
{
|
|
152
|
-
"profile": {
|
|
153
|
-
/* User profile data */
|
|
154
|
-
},
|
|
155
|
-
"personalizations": [
|
|
156
|
-
{
|
|
157
|
-
/* Personalization/experience configuration for the associated profile */
|
|
158
|
-
}
|
|
159
|
-
],
|
|
160
|
-
"changes": [
|
|
161
|
-
{
|
|
162
|
-
/* Similar to `personalizations` but currently used for Custom Flags */
|
|
163
|
-
}
|
|
164
|
-
]
|
|
165
|
-
}
|
|
166
|
-
```
|
|
167
|
-
|
|
168
|
-
#### Get Profile data
|
|
169
|
-
|
|
170
|
-
```ts
|
|
171
|
-
const client = new ApiClient({ clientId: 'abc123' })
|
|
172
|
-
const { profile } = await client.experience.getProfile('profile-123', { locale: 'de-DE' })
|
|
173
|
-
```
|
|
174
|
-
|
|
175
|
-
#### Create a New Profile
|
|
123
|
+
Experience API methods are scoped to `client.experience` and return profile and optimization data:
|
|
176
124
|
|
|
177
125
|
```ts
|
|
178
|
-
const
|
|
179
|
-
const { profile } = await client.experience.createProfile({ events: [...] }, { locale: 'de-DE' })
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
#### Update an Existing Profile
|
|
183
|
-
|
|
184
|
-
```ts
|
|
185
|
-
const client = new ApiClient({ clientId: 'abc123' })
|
|
186
|
-
const { profile } = await client.experience.updateProfile(
|
|
187
|
-
{
|
|
188
|
-
profileId: 'profile-123',
|
|
189
|
-
events: [...],
|
|
190
|
-
},
|
|
191
|
-
{ locale: 'de-DE' }
|
|
192
|
-
)
|
|
193
|
-
```
|
|
194
|
-
|
|
195
|
-
#### Upsert a Profile
|
|
196
|
-
|
|
197
|
-
```ts
|
|
198
|
-
const client = new ApiClient({ clientId: 'abc123' })
|
|
199
|
-
const { profile } = await client.experience.upsertProfile(
|
|
200
|
-
{
|
|
201
|
-
profileId,
|
|
202
|
-
events: [...],
|
|
203
|
-
},
|
|
204
|
-
{ locale: 'de-DE' }
|
|
205
|
-
)
|
|
206
|
-
```
|
|
207
|
-
|
|
208
|
-
#### Upsert Many Profiles
|
|
209
|
-
|
|
210
|
-
The `upsertManyProfiles` method returns a `Promise` that resolves with an array of user profiles.
|
|
211
|
-
The `events` array must contain at least one event. Each event should have an additional
|
|
212
|
-
`anonymousId` property set to the associated anonymous ID or profile ID.
|
|
213
|
-
|
|
214
|
-
```ts
|
|
215
|
-
const client = new ApiClient({ clientId: 'abc123' })
|
|
216
|
-
const profiles = await client.experience.upsertManyProfiles(
|
|
126
|
+
const { profile, selectedOptimizations, changes } = await client.experience.upsertProfile(
|
|
217
127
|
{
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
anonymousId: 'anon-123',
|
|
221
|
-
// valid Experience event payload fields
|
|
222
|
-
},
|
|
223
|
-
],
|
|
128
|
+
profileId: 'profile-id',
|
|
129
|
+
events: [pageEvent],
|
|
224
130
|
},
|
|
225
131
|
{ locale: 'de-DE' },
|
|
226
132
|
)
|
|
227
133
|
```
|
|
228
134
|
|
|
229
|
-
|
|
135
|
+
Common methods include `getProfile`, `createProfile`, `updateProfile`, `upsertProfile`, and
|
|
136
|
+
`upsertManyProfiles`.
|
|
230
137
|
|
|
231
|
-
Insights API
|
|
232
|
-
`Promise` that resolves to `boolean`.
|
|
138
|
+
### Insights API
|
|
233
139
|
|
|
234
|
-
|
|
140
|
+
Insights API methods are scoped to `client.insights` and send analytics event batches:
|
|
235
141
|
|
|
236
142
|
```ts
|
|
237
|
-
const client = new ApiClient({ clientId: 'abc123' })
|
|
238
143
|
await client.insights.sendBatchEvents([
|
|
239
144
|
{
|
|
240
|
-
profile
|
|
241
|
-
events: [
|
|
242
|
-
|
|
243
|
-
type: 'component',
|
|
244
|
-
componentId: 'hero-banner',
|
|
245
|
-
componentType: 'Entry',
|
|
246
|
-
variantIndex: 0,
|
|
247
|
-
...,
|
|
248
|
-
},
|
|
249
|
-
],
|
|
250
|
-
}
|
|
145
|
+
profile,
|
|
146
|
+
events: [viewEvent],
|
|
147
|
+
},
|
|
251
148
|
])
|
|
252
149
|
```
|
|
253
150
|
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
The Event Builder is a helper class that assists in constructing valid events for submission to the
|
|
257
|
-
Experience and Insights APIs.
|
|
258
|
-
|
|
259
|
-
### Event Builder Configuration
|
|
260
|
-
|
|
261
|
-
Event Builder configuration options assist in adding contextual data to each event created by a
|
|
262
|
-
builder instance.
|
|
263
|
-
|
|
264
|
-
| Option | Required? | Default | Description |
|
|
265
|
-
| ------------------- | --------- | ------------------------------- | ---------------------------------------------------------------------------------- |
|
|
266
|
-
| `app` | No | `undefined` | The application definition used to attribute events to a specific consumer app |
|
|
267
|
-
| `channel` | Yes | N/A | The channel that identifies where events originate from (e.g. `'web'`, `'mobile'`) |
|
|
268
|
-
| `library` | Yes | N/A | The client library metadata that is attached to all events |
|
|
269
|
-
| `getLocale` | No | `() => 'en-US'` | Function used to resolve the locale for outgoing events |
|
|
270
|
-
| `getPageProperties` | No | `() => DEFAULT_PAGE_PROPERTIES` | Function that returns the current page properties |
|
|
271
|
-
| `getUserAgent` | No | `() => undefined` | Function used to obtain the current user agent string when applicable |
|
|
272
|
-
|
|
273
|
-
The `get*` functions are most useful in stateful environments. Stateless environments should set the
|
|
274
|
-
related data directly via Event Builder method arguments.
|
|
275
|
-
|
|
276
|
-
The `channel` option may contain one of the following values:
|
|
277
|
-
|
|
278
|
-
- `web`
|
|
279
|
-
- `mobile`
|
|
280
|
-
- `server`
|
|
281
|
-
|
|
282
|
-
Configuration method signatures:
|
|
151
|
+
Insights endpoints do not return response data. For last-chance browser lifecycle delivery, pass a
|
|
152
|
+
per-call `beacon` sender that receives the request URL and already serialized body.
|
|
283
153
|
|
|
284
|
-
|
|
285
|
-
- `getPageProperties`:
|
|
154
|
+
### Fetch helpers
|
|
286
155
|
|
|
287
|
-
|
|
288
|
-
() => {
|
|
289
|
-
path: string,
|
|
290
|
-
query: Record<string, string>,
|
|
291
|
-
referrer: string,
|
|
292
|
-
search: string,
|
|
293
|
-
title?: string,
|
|
294
|
-
url: string
|
|
295
|
-
}
|
|
296
|
-
```
|
|
156
|
+
This package also exports fetch helper functions used by SDK layers:
|
|
297
157
|
|
|
298
|
-
|
|
158
|
+
| Helper | Purpose |
|
|
159
|
+
| ---------------------------- | ------------------------------------------------------- |
|
|
160
|
+
| `createProtectedFetchMethod` | Adds timeout and retry protection around a fetch method |
|
|
161
|
+
| `createRetryFetchMethod` | Applies retry policy to retryable responses |
|
|
162
|
+
| `createTimeoutFetchMethod` | Aborts requests after the configured timeout |
|
|
299
163
|
|
|
300
|
-
|
|
164
|
+
Use generated reference docs for helper signatures and callback payloads.
|
|
301
165
|
|
|
302
|
-
|
|
303
|
-
component
|
|
304
|
-
- `buildComponentView`: Builds a component view event payload for a Contentful entry-based component
|
|
305
|
-
- `buildFlagView`: Builds a component view payload event for a Custom Flag component
|
|
306
|
-
- `buildIdentify`: Builds an identify event payload to associate a user ID with traits
|
|
307
|
-
- `buildPageView`: Builds a page view event payload
|
|
308
|
-
- `buildScreenView`: Builds a screen view event payload
|
|
309
|
-
- `buildTrack`: Builds a track event payload for arbitrary user actions
|
|
166
|
+
## Related
|
|
310
167
|
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
168
|
+
- [API Client generated reference](https://contentful.github.io/optimization/modules/_contentful_optimization-api-client.html) -
|
|
169
|
+
exported API reference
|
|
170
|
+
- [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
|
|
171
|
+
- [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
|
|
172
|
+
client
|
|
173
|
+
- [Choosing the right SDK](https://contentful.github.io/optimization/documents/Documentation.Guides.choosing-the-right-sdk.html) -
|
|
174
|
+
package selection guidance for application integrations
|