@contentful/optimization-api-client 0.1.0-alpha14 → 0.1.0-alpha16

package/dist/index.d.cts

@@ -213,7 +213,8 @@ export declare interface BaseFetchMethodOptions {
      *
      * @remarks
      * This is useful for providing polyfills, mocks, or instrumented fetch
-     * implementations.
+     * implementations. It is required in runtimes that do not provide
+     * `globalThis.fetch`.
      */
     fetchMethod?: FetchMethod;
 }
@@ -609,14 +610,16 @@ export declare type Feature = 'ip-enrichment' | 'location';
  *
  * @example
  * ```ts
- * const method: FetchMethod = async (url, init) => {
- *   return fetch(url, init)
+ * const method: FetchMethod = async (input, init) => {
+ *   return fetch(input, init)
  * }
  * ```
  *
  * @public
  */
-export declare type FetchMethod = (url: string | URL, init: RequestInit) => Promise<Response>;
+export declare type FetchInput = string | Request;
+
+export declare type FetchMethod = (input: FetchInput, init?: RequestInit) => Promise<Response>;
 
 /**
  * Options passed to callback functions invoked by fetch wrappers.
@@ -664,7 +667,7 @@ export declare const INSIGHTS_BASE_URL = "https://ingest.insights.ninetailed.co/
  *
  * @remarks
  * This client is optimized for sending batched events, optionally using a
- * custom beacon-like handler when available.
+ * custom beacon-like sender for last-chance lifecycle delivery.
  *
  * @example
  * ```ts
@@ -696,10 +699,6 @@ export declare class InsightsApiClient extends ApiClientBase {
      * Base URL used for Insights API requests.
      */
     protected readonly baseUrl: string;
-    /**
-     * Optional handler used to enqueue events via the Beacon API or a similar mechanism.
-     */
-    private readonly beaconHandler;
     /**
      * Creates a new {@link InsightsApiClient} instance.
      *
@@ -710,9 +709,6 @@ export declare class InsightsApiClient extends ApiClientBase {
      * const client = new InsightsApiClient({
      *   clientId: 'org-id',
      *   environment: 'main',
-     *   beaconHandler: (url, data) => {
-     *     return navigator.sendBeacon(url.toString(), JSON.stringify(data))
-     *   },
      * })
      * ```
      */
@@ -721,18 +717,18 @@ export declare class InsightsApiClient extends ApiClientBase {
      * Sends batches of insights events to the Ninetailed Insights API.
      *
      * @param batches - Array of event batches to send.
-     * @param options - Optional request options, including a per-call `beaconHandler`.
+     * @param options - Optional request options, including a per-call `beacon` sender.
      * @returns `true` when the event batch is successfully queued by the beacon
-     * handler or a direct request is successfully sent, `false` otherwise.
+     * sender or a direct request is successfully sent, `false` otherwise.
      *
      * @remarks
-     * If a `beaconHandler` is provided (either in the method call or in the
-     * client configuration) it will be invoked first. When the handler returns
-     * `true`, the events are considered successfully queued and no network
-     * request is made by this method.
+     * If a `beacon` sender is provided, it will be invoked first with the
+     * serialized request body. When the sender returns `true`, the events are
+     * considered successfully queued and no network request is made by this
+     * method.
      *
-     * If the handler is missing or returns `false`, the events are emitted
-     * immediately via `fetch`.
+     * If the sender is missing, returns `false`, or throws, the events are
+     * emitted immediately via `fetch`.
      *
      * @example
      * ```ts
@@ -741,11 +737,9 @@ export declare class InsightsApiClient extends ApiClientBase {
      *
      * @example
      * ```ts
-     * // Override beaconHandler for a single call
+     * // Use Beacon for a last-chance lifecycle flush
      * const success = await insightsClient.sendBatchEvents(batches, {
-     *   beaconHandler: (url, data) => {
-     *     return navigator.sendBeacon(url.toString(), JSON.stringify(data))
-     *   },
+     *   beacon: (url, body) => navigator.sendBeacon(url, body),
      * })
      * ```
      */
@@ -757,7 +751,7 @@ export declare class InsightsApiClient extends ApiClientBase {
  *
  * @public
  */
-export declare interface InsightsApiClientConfig extends ApiConfig, InsightsApiClientRequestOptions {
+export declare interface InsightsApiClientConfig extends ApiConfig {
 }
 
 /**
@@ -767,18 +761,18 @@ export declare interface InsightsApiClientConfig extends ApiConfig, InsightsApiC
  */
 export declare interface InsightsApiClientRequestOptions {
     /**
-     * Handler used to enqueue events via the Beacon API or a similar mechanism.
+     * Sender used to enqueue serialized events via the Beacon API or a similar mechanism.
      *
      * @param url - Target URL for the batched events.
-     * @param data - Array of batched insights events to be sent.
+     * @param body - Serialized batched insights events to be sent.
      * @returns `true` if the events were successfully queued, `false` otherwise.
      *
      * @remarks
-     * When provided, this handler is preferred over direct `fetch` calls. If it
-     * returns `false`, the client falls back to emitting events immediately via
-     * `fetch`.
+     * This option is intended for last-chance lifecycle delivery. If it returns
+     * `false` or throws, the client falls back to emitting events immediately via
+     * `fetch` with `keepalive`.
      */
-    beaconHandler?: (url: string | URL, data: BatchInsightsEventArray) => boolean;
+    beacon?: (url: string, body: string) => boolean;
 }
 
 /**

package/dist/index.d.mts

@@ -213,7 +213,8 @@ export declare interface BaseFetchMethodOptions {
      *
      * @remarks
      * This is useful for providing polyfills, mocks, or instrumented fetch
-     * implementations.
+     * implementations. It is required in runtimes that do not provide
+     * `globalThis.fetch`.
      */
     fetchMethod?: FetchMethod;
 }
@@ -609,14 +610,16 @@ export declare type Feature = 'ip-enrichment' | 'location';
  *
  * @example
  * ```ts
- * const method: FetchMethod = async (url, init) => {
- *   return fetch(url, init)
+ * const method: FetchMethod = async (input, init) => {
+ *   return fetch(input, init)
  * }
  * ```
  *
  * @public
  */
-export declare type FetchMethod = (url: string | URL, init: RequestInit) => Promise<Response>;
+export declare type FetchInput = string | Request;
+
+export declare type FetchMethod = (input: FetchInput, init?: RequestInit) => Promise<Response>;
 
 /**
  * Options passed to callback functions invoked by fetch wrappers.
@@ -664,7 +667,7 @@ export declare const INSIGHTS_BASE_URL = "https://ingest.insights.ninetailed.co/
  *
  * @remarks
  * This client is optimized for sending batched events, optionally using a
- * custom beacon-like handler when available.
+ * custom beacon-like sender for last-chance lifecycle delivery.
  *
  * @example
  * ```ts
@@ -696,10 +699,6 @@ export declare class InsightsApiClient extends ApiClientBase {
      * Base URL used for Insights API requests.
      */
     protected readonly baseUrl: string;
-    /**
-     * Optional handler used to enqueue events via the Beacon API or a similar mechanism.
-     */
-    private readonly beaconHandler;
     /**
      * Creates a new {@link InsightsApiClient} instance.
      *
@@ -710,9 +709,6 @@ export declare class InsightsApiClient extends ApiClientBase {
      * const client = new InsightsApiClient({
      *   clientId: 'org-id',
      *   environment: 'main',
-     *   beaconHandler: (url, data) => {
-     *     return navigator.sendBeacon(url.toString(), JSON.stringify(data))
-     *   },
      * })
      * ```
      */
@@ -721,18 +717,18 @@ export declare class InsightsApiClient extends ApiClientBase {
      * Sends batches of insights events to the Ninetailed Insights API.
      *
      * @param batches - Array of event batches to send.
-     * @param options - Optional request options, including a per-call `beaconHandler`.
+     * @param options - Optional request options, including a per-call `beacon` sender.
      * @returns `true` when the event batch is successfully queued by the beacon
-     * handler or a direct request is successfully sent, `false` otherwise.
+     * sender or a direct request is successfully sent, `false` otherwise.
      *
      * @remarks
-     * If a `beaconHandler` is provided (either in the method call or in the
-     * client configuration) it will be invoked first. When the handler returns
-     * `true`, the events are considered successfully queued and no network
-     * request is made by this method.
+     * If a `beacon` sender is provided, it will be invoked first with the
+     * serialized request body. When the sender returns `true`, the events are
+     * considered successfully queued and no network request is made by this
+     * method.
      *
-     * If the handler is missing or returns `false`, the events are emitted
-     * immediately via `fetch`.
+     * If the sender is missing, returns `false`, or throws, the events are
+     * emitted immediately via `fetch`.
      *
      * @example
      * ```ts
@@ -741,11 +737,9 @@ export declare class InsightsApiClient extends ApiClientBase {
      *
      * @example
      * ```ts
-     * // Override beaconHandler for a single call
+     * // Use Beacon for a last-chance lifecycle flush
      * const success = await insightsClient.sendBatchEvents(batches, {
-     *   beaconHandler: (url, data) => {
-     *     return navigator.sendBeacon(url.toString(), JSON.stringify(data))
-     *   },
+     *   beacon: (url, body) => navigator.sendBeacon(url, body),
      * })
      * ```
      */
@@ -757,7 +751,7 @@ export declare class InsightsApiClient extends ApiClientBase {
  *
  * @public
  */
-export declare interface InsightsApiClientConfig extends ApiConfig, InsightsApiClientRequestOptions {
+export declare interface InsightsApiClientConfig extends ApiConfig {
 }
 
 /**
@@ -767,18 +761,18 @@ export declare interface InsightsApiClientConfig extends ApiConfig, InsightsApiC
  */
 export declare interface InsightsApiClientRequestOptions {
     /**
-     * Handler used to enqueue events via the Beacon API or a similar mechanism.
+     * Sender used to enqueue serialized events via the Beacon API or a similar mechanism.
      *
      * @param url - Target URL for the batched events.
-     * @param data - Array of batched insights events to be sent.
+     * @param body - Serialized batched insights events to be sent.
      * @returns `true` if the events were successfully queued, `false` otherwise.
      *
      * @remarks
-     * When provided, this handler is preferred over direct `fetch` calls. If it
-     * returns `false`, the client falls back to emitting events immediately via
-     * `fetch`.
+     * This option is intended for last-chance lifecycle delivery. If it returns
+     * `false` or throws, the client falls back to emitting events immediately via
+     * `fetch` with `keepalive`.
      */
-    beaconHandler?: (url: string | URL, data: BatchInsightsEventArray) => boolean;
+    beacon?: (url: string, body: string) => boolean;
 }
 
 /**

package/dist/index.d.ts

@@ -213,7 +213,8 @@ export declare interface BaseFetchMethodOptions {
      *
      * @remarks
      * This is useful for providing polyfills, mocks, or instrumented fetch
-     * implementations.
+     * implementations. It is required in runtimes that do not provide
+     * `globalThis.fetch`.
      */
     fetchMethod?: FetchMethod;
 }
@@ -609,14 +610,16 @@ export declare type Feature = 'ip-enrichment' | 'location';
  *
  * @example
  * ```ts
- * const method: FetchMethod = async (url, init) => {
- *   return fetch(url, init)
+ * const method: FetchMethod = async (input, init) => {
+ *   return fetch(input, init)
  * }
  * ```
  *
  * @public
  */
-export declare type FetchMethod = (url: string | URL, init: RequestInit) => Promise<Response>;
+export declare type FetchInput = string | Request;
+
+export declare type FetchMethod = (input: FetchInput, init?: RequestInit) => Promise<Response>;
 
 /**
  * Options passed to callback functions invoked by fetch wrappers.
@@ -664,7 +667,7 @@ export declare const INSIGHTS_BASE_URL = "https://ingest.insights.ninetailed.co/
  *
  * @remarks
  * This client is optimized for sending batched events, optionally using a
- * custom beacon-like handler when available.
+ * custom beacon-like sender for last-chance lifecycle delivery.
  *
  * @example
  * ```ts
@@ -696,10 +699,6 @@ export declare class InsightsApiClient extends ApiClientBase {
      * Base URL used for Insights API requests.
      */
     protected readonly baseUrl: string;
-    /**
-     * Optional handler used to enqueue events via the Beacon API or a similar mechanism.
-     */
-    private readonly beaconHandler;
     /**
      * Creates a new {@link InsightsApiClient} instance.
      *
@@ -710,9 +709,6 @@ export declare class InsightsApiClient extends ApiClientBase {
      * const client = new InsightsApiClient({
      *   clientId: 'org-id',
      *   environment: 'main',
-     *   beaconHandler: (url, data) => {
-     *     return navigator.sendBeacon(url.toString(), JSON.stringify(data))
-     *   },
      * })
      * ```
      */
@@ -721,18 +717,18 @@ export declare class InsightsApiClient extends ApiClientBase {
      * Sends batches of insights events to the Ninetailed Insights API.
      *
      * @param batches - Array of event batches to send.
-     * @param options - Optional request options, including a per-call `beaconHandler`.
+     * @param options - Optional request options, including a per-call `beacon` sender.
      * @returns `true` when the event batch is successfully queued by the beacon
-     * handler or a direct request is successfully sent, `false` otherwise.
+     * sender or a direct request is successfully sent, `false` otherwise.
      *
      * @remarks
-     * If a `beaconHandler` is provided (either in the method call or in the
-     * client configuration) it will be invoked first. When the handler returns
-     * `true`, the events are considered successfully queued and no network
-     * request is made by this method.
+     * If a `beacon` sender is provided, it will be invoked first with the
+     * serialized request body. When the sender returns `true`, the events are
+     * considered successfully queued and no network request is made by this
+     * method.
      *
-     * If the handler is missing or returns `false`, the events are emitted
-     * immediately via `fetch`.
+     * If the sender is missing, returns `false`, or throws, the events are
+     * emitted immediately via `fetch`.
      *
      * @example
      * ```ts
@@ -741,11 +737,9 @@ export declare class InsightsApiClient extends ApiClientBase {
      *
      * @example
      * ```ts
-     * // Override beaconHandler for a single call
+     * // Use Beacon for a last-chance lifecycle flush
      * const success = await insightsClient.sendBatchEvents(batches, {
-     *   beaconHandler: (url, data) => {
-     *     return navigator.sendBeacon(url.toString(), JSON.stringify(data))
-     *   },
+     *   beacon: (url, body) => navigator.sendBeacon(url, body),
      * })
      * ```
      */
@@ -757,7 +751,7 @@ export declare class InsightsApiClient extends ApiClientBase {
  *
  * @public
  */
-export declare interface InsightsApiClientConfig extends ApiConfig, InsightsApiClientRequestOptions {
+export declare interface InsightsApiClientConfig extends ApiConfig {
 }
 
 /**
@@ -767,18 +761,18 @@ export declare interface InsightsApiClientConfig extends ApiConfig, InsightsApiC
  */
 export declare interface InsightsApiClientRequestOptions {
     /**
-     * Handler used to enqueue events via the Beacon API or a similar mechanism.
+     * Sender used to enqueue serialized events via the Beacon API or a similar mechanism.
      *
      * @param url - Target URL for the batched events.
-     * @param data - Array of batched insights events to be sent.
+     * @param body - Serialized batched insights events to be sent.
      * @returns `true` if the events were successfully queued, `false` otherwise.
      *
      * @remarks
-     * When provided, this handler is preferred over direct `fetch` calls. If it
-     * returns `false`, the client falls back to emitting events immediately via
-     * `fetch`.
+     * This option is intended for last-chance lifecycle delivery. If it returns
+     * `false` or throws, the client falls back to emitting events immediately via
+     * `fetch` with `keepalive`.
      */
-    beaconHandler?: (url: string | URL, data: BatchInsightsEventArray) => boolean;
+    beacon?: (url: string, body: string) => boolean;
 }
 
 /**

package/dist/index.mjs

@@ -1,5 +1,15 @@
 import { createScopedLogger } from "./649.mjs";
 import { __rspack_external__contentful_optimization_api_schemas_66dcf407 } from "./199.mjs";
+const fetchInputToString = (input)=>{
+    if ('string' == typeof input) return input;
+    return input.url;
+};
+const MISSING_FETCH_METHOD_MESSAGE = 'No fetch implementation available. Provide a fetchMethod.';
+function resolveFetchMethod(fetchMethod) {
+    if (fetchMethod) return fetchMethod;
+    if ('function' == typeof globalThis.fetch) return globalThis.fetch.bind(globalThis);
+    throw new Error(MISSING_FETCH_METHOD_MESSAGE);
+}
 const logger = createScopedLogger('ApiClient:Retry');
 const DEFAULT_INTERVAL_TIMEOUT = 0;
 const DEFAULT_RETRY_COUNT = 1;
@@ -13,22 +23,23 @@ class HttpError extends Error {
         this.status = status;
     }
 }
-function createRetryFetchCallback({ apiName = 'Optimization', controller, fetchMethod = fetch, init, url }) {
+function createRetryFetchCallback({ apiName = 'Optimization', controller, fetchMethod, init, url }) {
     return async ()=>{
+        const urlLabel = fetchInputToString(url);
         try {
             const response = await fetchMethod(url, init);
-            if (response.status === RETRY_RESPONSE_STATUS) throw new HttpError(`${apiName} API request to "${url.toString()}" failed with status: "[${response.status}] ${response.statusText}".`, RETRY_RESPONSE_STATUS);
+            if (response.status === RETRY_RESPONSE_STATUS) throw new HttpError(`${apiName} API request to "${urlLabel}" failed with status: "[${response.status}] ${response.statusText}".`, RETRY_RESPONSE_STATUS);
             if (!response.ok) {
-                const httpError = new Error(`Request to "${url.toString()}" failed with status: [${response.status}] ${response.statusText} - traceparent: ${response.headers.get('traceparent')}`);
+                const httpError = new Error(`Request to "${urlLabel}" failed with status: [${response.status}] ${response.statusText} - traceparent: ${response.headers.get('traceparent')}`);
                 logger.error('Request failed with non-OK status:', httpError);
                 controller.abort();
                 return;
             }
-            logger.debug(`Response from "${url.toString()}":`, response);
+            logger.debug(`Response from "${urlLabel}":`, response);
             return response;
         } catch (error) {
             if (error instanceof HttpError && error.status === RETRY_RESPONSE_STATUS) throw error;
-            logger.error(`Request to "${url.toString()}" failed:`, error);
+            logger.error(`Request to "${urlLabel}" failed:`, error);
             controller.abort();
         }
     };
@@ -41,14 +52,15 @@ async function delayRetry(intervalTimeout) {
     }, intervalTimeout);
     await promise;
 }
-function createRetryFetchMethod({ apiName = 'Optimization', fetchMethod = fetch, intervalTimeout = DEFAULT_INTERVAL_TIMEOUT, onFailedAttempt, retries = DEFAULT_RETRY_COUNT } = {}) {
+function createRetryFetchMethod({ apiName = 'Optimization', fetchMethod, intervalTimeout = DEFAULT_INTERVAL_TIMEOUT, onFailedAttempt, retries = DEFAULT_RETRY_COUNT } = {}) {
+    const resolvedFetchMethod = resolveFetchMethod(fetchMethod);
     return async (url, init)=>{
         const controller = new AbortController();
         const maxAttempts = retries + 1;
         const attemptFetch = createRetryFetchCallback({
             apiName,
             controller,
-            fetchMethod,
+            fetchMethod: resolvedFetchMethod,
             init,
             url
         });
@@ -68,28 +80,32 @@ function createRetryFetchMethod({ apiName = 'Optimization', fetchMethod = fetch,
             if (0 === retriesLeft) throw error;
             await delayRetry(intervalTimeout);
         }
-        throw new Error(`${apiName} API request to "${url.toString()}" may not be retried.`);
+        throw new Error(`${apiName} API request to "${fetchInputToString(url)}" may not be retried.`);
     };
 }
 const createTimeoutFetchMethod_logger = createScopedLogger('ApiClient:Timeout');
 const DEFAULT_REQUEST_TIMEOUT = 3000;
-function createTimeoutFetchMethod({ apiName = 'Optimization', fetchMethod = fetch, onRequestTimeout, requestTimeout = DEFAULT_REQUEST_TIMEOUT } = {}) {
+function isFetchAbortSignal(signal) {
+    return 'object' == typeof signal && null !== signal;
+}
+function createTimeoutFetchMethod({ apiName = 'Optimization', fetchMethod, onRequestTimeout, requestTimeout = DEFAULT_REQUEST_TIMEOUT } = {}) {
+    const resolvedFetchMethod = resolveFetchMethod(fetchMethod);
     return async (url, init)=>{
         const controller = new AbortController();
         const id = setTimeout(()=>{
             if ('function' == typeof onRequestTimeout) onRequestTimeout({
                 apiName
             });
-            else createTimeoutFetchMethod_logger.error(`Request to "${url.toString()}" timed out`, new Error('Request timeout'));
+            else createTimeoutFetchMethod_logger.error(`Request to "${fetchInputToString(url)}" timed out`, new Error('Request timeout'));
             controller.abort();
         }, requestTimeout);
+        const { signal } = controller;
+        if (!isFetchAbortSignal(signal)) throw new Error('AbortController signal is not compatible with fetch.');
         const requestInit = {
-            ...init
+            ...init,
+            signal
         };
-        Object.assign(requestInit, {
-            signal: controller.signal
-        });
-        const response = await fetchMethod(url, requestInit);
+        const response = await resolvedFetchMethod(url, requestInit);
         clearTimeout(id);
         return response;
     };
@@ -113,7 +129,7 @@ const Fetch = {
     create: createProtectedFetchMethod
 };
 const fetch_Fetch = Fetch;
-const src_fetch = fetch_Fetch;
+const fetch = fetch_Fetch;
 const ApiClientBase_logger = createScopedLogger('ApiClient');
 const DEFAULT_ENVIRONMENT = 'main';
 class ApiClientBase {
@@ -125,7 +141,7 @@ class ApiClientBase {
         this.clientId = clientId;
         this.environment = environment ?? DEFAULT_ENVIRONMENT;
         this.name = name;
-        this.fetch = src_fetch.create({
+        this.fetch = fetch.create({
             ...fetchOptions ?? {},
             apiName: name
         });
@@ -310,37 +326,42 @@ class ExperienceApiClient extends src_ApiClientBase {
     }
 }
 const InsightsApiClient_logger = createScopedLogger('ApiClient:Insights');
+const BEACON_FALLBACK_MESSAGE = 'beacon failed; falling back to fetch';
 const INSIGHTS_BASE_URL = 'https://ingest.insights.ninetailed.co/';
 class InsightsApiClient extends src_ApiClientBase {
     baseUrl;
-    beaconHandler;
     constructor(config){
         super('Insights', config);
-        const { baseUrl, beaconHandler } = config;
+        const { baseUrl } = config;
         this.baseUrl = baseUrl || INSIGHTS_BASE_URL;
-        this.beaconHandler = beaconHandler;
     }
     async sendBatchEvents(batches, options = {}) {
-        const { beaconHandler = this.beaconHandler } = options;
+        const { beacon } = options;
         const url = new URL(`v1/organizations/${this.clientId}/environments/${this.environment}/events`, this.baseUrl);
+        const urlString = url.toString();
         const body = (0, __rspack_external__contentful_optimization_api_schemas_66dcf407.parseWithFriendlyError)(__rspack_external__contentful_optimization_api_schemas_66dcf407.BatchInsightsEventArray, batches);
-        if ('function' == typeof beaconHandler) {
-            InsightsApiClient_logger.debug('Queueing events via beaconHandler');
-            const beaconSuccessfullyQueued = beaconHandler(url, body);
-            if (beaconSuccessfullyQueued) return true;
-            InsightsApiClient_logger.warn('beaconHandler failed to queue events; events will be emitted immediately via fetch');
+        const serializedBody = JSON.stringify(body);
+        if (beacon) {
+            InsightsApiClient_logger.debug('Queueing events via beacon');
+            try {
+                const beaconSuccessfullyQueued = beacon(urlString, serializedBody);
+                if (beaconSuccessfullyQueued) return true;
+                InsightsApiClient_logger.warn(BEACON_FALLBACK_MESSAGE);
+            } catch (error) {
+                InsightsApiClient_logger.warn(BEACON_FALLBACK_MESSAGE, error);
+            }
         }
         const requestName = 'Event Batches';
         InsightsApiClient_logger.info(`Sending "${requestName}" request`);
         InsightsApiClient_logger.debug(`"${requestName}" request body:`, body);
         try {
-            await this.fetch(url, {
+            await this.fetch(urlString, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json'
                 },
-                body: JSON.stringify(body),
-                keepalive: true
+                body: serializedBody,
+                keepalive: !!beacon
             });
             InsightsApiClient_logger.debug(`"${requestName}" request successfully completed`);
             return true;