@contentful/optimization-api-client 0.1.0-alpha

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (C) 2026 Contentful Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,282 @@
+<p align="center">
+  <a href="https://www.contentful.com/developers/docs/personalization/">
+    <img alt="Contentful Logo" title="Contentful" src="../../contentful-icon.png" width="150">
+  </a>
+</p>
+
+<h1 align="center">Contentful Personalization & Analytics</h1>
+
+<h3 align="center">API Client</h3>
+
+<div align="center">
+
+[Readme](./README.md) · [Reference](https://contentful.github.io/optimization) ·
+[Contributing](/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]
+>
+> In the future, the Experience and Insights APIs may be combined behind an Optimization API
+
+<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)
+  - [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)
+
+<!-- mtoc-end -->
+</details>
+
+## Getting Started
+
+Install using an NPM-compatible package manager, pnpm for example:
+
+```sh
+pnpm install @contentful/optimization-api-client
+```
+
+Import the 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' })
+```
+
+## 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
+
+### 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
+
+```ts
+const client = new ApiClient({ clientId: 'abc123' })
+const { profile } = await client.personalization.updateProfile(
+  {
+    profileId: 'profile-123',
+    events: [...],
+  },
+  { 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
+
+Insights API methods are scoped to the client's `analytics` member. All analytics methods return a
+`Promise` that resolves to `void` (no value).
+
+#### Send Batch Events
+
+```ts
+const client = new ApiClient({ clientId: 'abc123' })
+await client.analytics.sendBatchEvents([
+  {
+    profile: { id: 'abc-123', ... },
+    events: [{ type: 'track', ... }],
+  }
+])
+```
+
+## 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:
+
+- `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
+
+- `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
+
+See the
+[Event Builder documentation](../classes/_contentful_optimization-api-client.EventBuilder.html) for
+more information regarding arguments and return values.

package/dist/ApiClient.d.ts

@@ -0,0 +1,74 @@
+import type { ApiConfig, GlobalApiConfigProperties } from './ApiClientBase';
+import ExperienceApiClient, { type ExperienceApiClientConfig } from './experience';
+import InsightsApiClient, { type InsightsApiClientConfig } from './insights';
+/**
+ * Configuration for the high-level {@link ApiClient}.
+ *
+ * @public
+ */
+export interface ApiClientConfig extends Pick<ApiConfig, GlobalApiConfigProperties> {
+    /**
+     * Configuration for the personalization (Experience) API client.
+     *
+     * @remarks
+     * Any properties shared with {@link ApiConfig} are taken from the top-level
+     * config and overridden by this object when specified.
+     */
+    personalization?: Omit<ExperienceApiClientConfig, GlobalApiConfigProperties>;
+    /**
+     * Configuration for the analytics (Insights) API client.
+     *
+     * @remarks
+     * Any properties shared with {@link ApiConfig} are taken from the top-level
+     * config and overridden by this object when specified.
+     */
+    analytics?: Omit<InsightsApiClientConfig, GlobalApiConfigProperties>;
+}
+/**
+ * Aggregated API client providing access to Experience and Insights APIs.
+ *
+ * @public
+ *
+ * @remarks
+ * This client encapsulates shared configuration and exposes dedicated
+ * sub-clients for personalization and analytics use cases.
+ *
+ * @example
+ * ```ts
+ * const client = new ApiClient({
+ *   clientId: 'org-id',
+ *   environment: 'main',
+ *   preview: false,
+ *   personalization: {
+ *     // experience-specific overrides
+ *   },
+ *   analytics: {
+ *     // insights-specific overrides
+ *   },
+ * })
+ *
+ * const profile = await client.experience.getProfile('profile-id')
+ * const batch = await client.insights.upsertManyProfiles({ events: batchEvents })
+ * ```
+ */
+export default class ApiClient {
+    /**
+     * Shared configuration applied to both Experience and Insights clients.
+     */
+    readonly config: ApiConfig;
+    /**
+     * Client for personalization and experience-related operations.
+     */
+    readonly experience: ExperienceApiClient;
+    /**
+     * Client for analytics and insights-related operations.
+     */
+    readonly insights: InsightsApiClient;
+    /**
+     * Creates a new aggregated {@link ApiClient} instance.
+     *
+     * @param config - Global API client configuration with optional per-client overrides.
+     */
+    constructor(config: ApiClientConfig);
+}
+//# sourceMappingURL=ApiClient.d.ts.map

package/dist/ApiClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiClient.d.ts","sourceRoot":"","sources":["../src/ApiClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAA;AAC3E,OAAO,mBAAmB,EAAE,EAAE,KAAK,yBAAyB,EAAE,MAAM,cAAc,CAAA;AAClF,OAAO,iBAAiB,EAAE,EAAE,KAAK,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAE5E;;;;GAIG;AACH,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,SAAS,EAAE,yBAAyB,CAAC;IACjF;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,IAAI,CAAC,yBAAyB,EAAE,yBAAyB,CAAC,CAAA;IAE5E;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC,uBAAuB,EAAE,yBAAyB,CAAC,CAAA;CACrE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,OAAO,OAAO,SAAS;IAC5B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;IAE1B;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAA;IAExC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAA;IAEpC;;;;OAIG;gBACS,MAAM,EAAE,eAAe;CAepC"}

package/dist/ApiClient.js

@@ -0,0 +1,61 @@
+import ExperienceApiClient from './experience';
+import InsightsApiClient from './insights';
+/**
+ * Aggregated API client providing access to Experience and Insights APIs.
+ *
+ * @public
+ *
+ * @remarks
+ * This client encapsulates shared configuration and exposes dedicated
+ * sub-clients for personalization and analytics use cases.
+ *
+ * @example
+ * ```ts
+ * const client = new ApiClient({
+ *   clientId: 'org-id',
+ *   environment: 'main',
+ *   preview: false,
+ *   personalization: {
+ *     // experience-specific overrides
+ *   },
+ *   analytics: {
+ *     // insights-specific overrides
+ *   },
+ * })
+ *
+ * const profile = await client.experience.getProfile('profile-id')
+ * const batch = await client.insights.upsertManyProfiles({ events: batchEvents })
+ * ```
+ */
+export default class ApiClient {
+    /**
+     * Shared configuration applied to both Experience and Insights clients.
+     */
+    config;
+    /**
+     * Client for personalization and experience-related operations.
+     */
+    experience;
+    /**
+     * Client for analytics and insights-related operations.
+     */
+    insights;
+    /**
+     * Creates a new aggregated {@link ApiClient} instance.
+     *
+     * @param config - Global API client configuration with optional per-client overrides.
+     */
+    constructor(config) {
+        const { personalization, analytics, ...apiConfig } = config;
+        this.config = apiConfig;
+        this.experience = new ExperienceApiClient({
+            ...apiConfig,
+            ...personalization,
+        });
+        this.insights = new InsightsApiClient({
+            ...apiConfig,
+            ...analytics,
+        });
+    }
+}
+//# sourceMappingURL=ApiClient.js.map

package/dist/ApiClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiClient.js","sourceRoot":"","sources":["../src/ApiClient.ts"],"names":[],"mappings":"AACA,OAAO,mBAAuD,MAAM,cAAc,CAAA;AAClF,OAAO,iBAAmD,MAAM,YAAY,CAAA;AA2B5E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,OAAO,OAAO,SAAS;IAC5B;;OAEG;IACM,MAAM,CAAW;IAE1B;;OAEG;IACM,UAAU,CAAqB;IAExC;;OAEG;IACM,QAAQ,CAAmB;IAEpC;;;;OAIG;IACH,YAAY,MAAuB;QACjC,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,GAAG,MAAM,CAAA;QAE3D,IAAI,CAAC,MAAM,GAAG,SAAS,CAAA;QAEvB,IAAI,CAAC,UAAU,GAAG,IAAI,mBAAmB,CAAC;YACxC,GAAG,SAAS;YACZ,GAAG,eAAe;SACnB,CAAC,CAAA;QAEF,IAAI,CAAC,QAAQ,GAAG,IAAI,iBAAiB,CAAC;YACpC,GAAG,SAAS;YACZ,GAAG,SAAS;SACb,CAAC,CAAA;IACJ,CAAC;CACF"}

package/dist/ApiClientBase.d.ts

@@ -0,0 +1,113 @@
+import { type FetchMethod, type ProtectedFetchMethodOptions } from './fetch';
+/**
+ * Configuration options for API clients extending {@link ApiClientBase}.
+ *
+ * @public
+ */
+export 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.
+     *
+     * @remarks
+     * Defaults to `main` when not provided.
+     */
+    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;
+}
+/**
+ * Properties that may be shared between global and per-client API configuration.
+ *
+ * @public
+ */
+export type GlobalApiConfigProperties = 'environment' | 'fetchOptions' | 'clientId';
+/**
+ * Base class for API clients that provides shared configuration and error logging.
+ *
+ * @internal
+ *
+ * @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()
+ *   }
+ * }
+ * ```
+ */
+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.
+     *
+     * @protected
+     *
+     * @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;
+}
+export default ApiClientBase;
+//# sourceMappingURL=ApiClientBase.d.ts.map

package/dist/ApiClientBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiClientBase.d.ts","sourceRoot":"","sources":["../src/ApiClientBase.ts"],"names":[],"mappings":"AACA,OAAc,EAAE,KAAK,WAAW,EAAE,KAAK,2BAA2B,EAAE,MAAM,SAAS,CAAA;AAWnF;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,IAAI,CAAC,2BAA2B,EAAE,SAAS,CAAC,CAAA;IAE3D;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG,aAAa,GAAG,cAAc,GAAG,UAAU,CAAA;AAEnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,uBAAe,aAAa;IAC1B;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAE/B;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IAEnC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAEtC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAErC;;;;;OAKG;gBACS,IAAI,EAAE,MAAM,EAAE,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,EAAE,SAAS;IAQ5E;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,WAAW,EAAE,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;CAW1F;AAED,eAAe,aAAa,CAAA"}

package/dist/ApiClientBase.js

@@ -0,0 +1,94 @@
+import { createScopedLogger } from 'logger';
+import Fetch from './fetch';
+const logger = createScopedLogger('ApiClient');
+/**
+ * Default Contentful environment used when none is explicitly provided.
+ *
+ * @internal
+ */
+const DEFAULT_ENVIRONMENT = 'main';
+/**
+ * Base class for API clients that provides shared configuration and error logging.
+ *
+ * @internal
+ *
+ * @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()
+ *   }
+ * }
+ * ```
+ */
+class ApiClientBase {
+    /**
+     * Name of the API client, used in log messages and as the `apiName` for fetch.
+     */
+    name;
+    /**
+     * Client identifier used for authentication or tracking.
+     */
+    clientId;
+    /**
+     * Contentful environment associated with this client.
+     */
+    environment;
+    /**
+     * Protected fetch method used by the client to perform HTTP requests.
+     */
+    fetch;
+    /**
+     * 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, { fetchOptions, clientId, environment }) {
+        this.clientId = clientId;
+        this.environment = environment ?? DEFAULT_ENVIRONMENT;
+        this.name = name;
+        this.fetch = Fetch.create({ ...(fetchOptions ?? {}), apiName: name });
+    }
+    /**
+     * 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.
+     *
+     * @protected
+     *
+     * @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.
+     */
+    logRequestError(error, { requestName }) {
+        if (error instanceof Error) {
+            if (error.name === 'AbortError') {
+                logger.warn(`[${this.name}] "${requestName}" request aborted due to network issues. This request may not be retried.`);
+            }
+            else {
+                logger.error(`[${this.name}] "${requestName}" request failed:`, error);
+            }
+        }
+    }
+}
+export default ApiClientBase;
+//# sourceMappingURL=ApiClientBase.js.map

package/dist/ApiClientBase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiClientBase.js","sourceRoot":"","sources":["../src/ApiClientBase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAA;AAC3C,OAAO,KAA6D,MAAM,SAAS,CAAA;AAEnF,MAAM,MAAM,GAAG,kBAAkB,CAAC,WAAW,CAAC,CAAA;AAE9C;;;;GAIG;AACH,MAAM,mBAAmB,GAAG,MAAM,CAAA;AA8ClC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAe,aAAa;IAC1B;;OAEG;IACgB,IAAI,CAAQ;IAE/B;;OAEG;IACgB,QAAQ,CAAQ;IAEnC;;OAEG;IACgB,WAAW,CAAQ;IAEtC;;OAEG;IACgB,KAAK,CAAa;IAErC;;;;;OAKG;IACH,YAAY,IAAY,EAAE,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAa;QAC1E,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;QACxB,IAAI,CAAC,WAAW,GAAG,WAAW,IAAI,mBAAmB,CAAA;QACrD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAEhB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,YAAY,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAA;IACvE,CAAC;IAED;;;;;;;;;;;;OAYG;IACO,eAAe,CAAC,KAAc,EAAE,EAAE,WAAW,EAA2B;QAChF,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBAChC,MAAM,CAAC,IAAI,CACT,IAAI,IAAI,CAAC,IAAI,MAAM,WAAW,2EAA2E,CAC1G,CAAA;YACH,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,IAAI,MAAM,WAAW,mBAAmB,EAAE,KAAK,CAAC,CAAA;YACxE,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED,eAAe,aAAa,CAAA"}