@contentful/optimization-api-client 0.1.0-alpha

package/dist/fetch/createRetryFetchMethod.js

@@ -0,0 +1,138 @@
+import { createScopedLogger } from 'logger';
+import retry from 'p-retry';
+const logger = createScopedLogger('ApiClient:Retry');
+/**
+ * Default interval (in milliseconds) between retry attempts.
+ *
+ * @internal
+ */
+const DEFAULT_INTERVAL_TIMEOUT = 0;
+/**
+ * Default number of retry attempts.
+ *
+ * @internal
+ */
+const DEFAULT_RETRY_COUNT = 1;
+/**
+ * HTTP status code that triggers a retry.
+ *
+ * @internal
+ *
+ * @remarks
+ * This value is currently fixed to `503 Service Unavailable`.
+ */
+const RETRY_RESPONSE_STATUS = 503;
+/**
+ * Default HTTP status code used for {@link HttpError}.
+ *
+ * @internal
+ */
+const HTTP_ERROR_RESPONSE_STATUS = 500;
+/**
+ * Error type representing HTTP failures with an associated status code.
+ *
+ * @internal
+ */
+class HttpError extends Error {
+    /**
+     * The HTTP status code associated with the error.
+     */
+    status;
+    /**
+     * Creates a new {@link HttpError}.
+     *
+     * @param message - Description of the error.
+     * @param status - HTTP status code associated with the error.
+     */
+    constructor(message, status = HTTP_ERROR_RESPONSE_STATUS) {
+        super(message);
+        Object.setPrototypeOf(this, HttpError.prototype);
+        this.status = status;
+    }
+}
+/**
+ * Creates a callback function used by `p-retry` to perform a fetch with retry logic.
+ *
+ * @param options - Internal options controlling the retry behavior.
+ * @returns A function that, when invoked, performs the fetch and applies retry rules.
+ *
+ * @internal
+ */
+function createRetryFetchCallback({ apiName = 'Optimization', controller, fetchMethod = fetch, init, url, }) {
+    return async () => {
+        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.ok) {
+                const httpError = new Error(`Request to "${url.toString()}" 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);
+            return response;
+        }
+        catch (error) {
+            if (error instanceof HttpError && error.status === RETRY_RESPONSE_STATUS) {
+                throw error;
+            }
+            logger.error(`Request to "${url.toString()}" failed:`, error);
+            controller.abort();
+        }
+    };
+}
+/**
+ * Creates a {@link FetchMethod} that retries failed requests according to the
+ * provided configuration.
+ *
+ * @param options - Configuration options that control retry behavior.
+ * @returns A {@link FetchMethod} that automatically retries qualifying failures.
+ *
+ * @remarks
+ * This wrapper integrates with `p-retry` and uses an {@link AbortController}
+ * to cancel pending requests when a non-retriable error occurs.
+ *
+ * @throws {@link Error}
+ * Thrown when the request cannot be retried and no successful response is obtained.
+ *
+ * @example
+ * ```ts
+ * const fetchWithRetry = createRetryFetchMethod({
+ *   apiName: 'Optimization',
+ *   retries: 3,
+ *   intervalTimeout: 200,
+ *   onFailedAttempt: ({ attemptNumber, retriesLeft }) => {
+ *     console.warn(`Attempt ${attemptNumber} failed. Retries left: ${retriesLeft}`)
+ *   },
+ * })
+ *
+ * const response = await fetchWithRetry('https://example.com', { method: 'GET' })
+ * ```
+ */
+export function createRetryFetchMethod({ apiName = 'Optimization', fetchMethod = fetch, intervalTimeout = DEFAULT_INTERVAL_TIMEOUT, onFailedAttempt, retries = DEFAULT_RETRY_COUNT, } = {}) {
+    return async (url, init) => {
+        const controller = new AbortController();
+        let retryResponse = undefined;
+        try {
+            retryResponse = await retry(createRetryFetchCallback({ apiName, controller, fetchMethod, init, url }), {
+                minTimeout: intervalTimeout,
+                onFailedAttempt: (options) => onFailedAttempt?.({ ...options, apiName }),
+                retries,
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            // Abort errors caused by timeouts should not bubble up and be reported by third-party tools (e.g. Sentry)
+            if (!(error instanceof Error) || error.name !== 'AbortError') {
+                throw error;
+            }
+        }
+        if (!retryResponse) {
+            throw new Error(`${apiName} API request to "${url.toString()}" may not be retried.`);
+        }
+        return retryResponse;
+    };
+}
+//# sourceMappingURL=createRetryFetchMethod.js.map

package/dist/fetch/createRetryFetchMethod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createRetryFetchMethod.js","sourceRoot":"","sources":["../../src/fetch/createRetryFetchMethod.ts"],"names":[],"mappings":"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"}

package/dist/fetch/createTimeoutFetchMethod.d.ts

@@ -0,0 +1,51 @@
+import type { BaseFetchMethodOptions, FetchMethod, FetchMethodCallbackOptions } from './Fetch';
+/**
+ * Configuration options for {@link createTimeoutFetchMethod}.
+ */
+export interface TimeoutFetchMethodOptions extends BaseFetchMethodOptions {
+    /**
+     * Callback invoked when a request exceeds the configured timeout.
+     *
+     * @param options - Information about the timed-out request.
+     *
+     * @remarks
+     * If this callback is not provided, a default error is logged.
+     *
+     * @see {@link FetchMethodCallbackOptions}
+     */
+    onRequestTimeout?: (options: FetchMethodCallbackOptions) => void;
+    /**
+     * Maximum time (in milliseconds) to wait for a response before aborting the request.
+     *
+     * @remarks
+     * Defaults to {@link DEFAULT_REQUEST_TIMEOUT}.
+     */
+    requestTimeout?: number;
+}
+/**
+ * Creates a {@link FetchMethod} that aborts requests after a configurable timeout.
+ *
+ * @param options - Configuration options controlling timeout behavior.
+ * @returns A {@link FetchMethod} that enforces a timeout for each request.
+ *
+ * @remarks
+ * When a timeout occurs, the request is aborted using an {@link AbortController}.
+ * If `onRequestTimeout` is not provided, an error is logged by the {@link logger}.
+ *
+ * @example
+ * ```ts
+ * const fetchWithTimeout = createTimeoutFetchMethod({
+ *   apiName: 'Optimization',
+ *   requestTimeout: 5000,
+ *   onRequestTimeout: ({ apiName }) => {
+ *     console.warn(`${apiName} request timed out`)
+ *   },
+ * })
+ *
+ * const response = await fetchWithTimeout('https://example.com', { method: 'GET' })
+ * ```
+ *
+ * @see {@link TimeoutFetchMethodOptions}
+ */
+export declare function createTimeoutFetchMethod({ apiName, fetchMethod, onRequestTimeout, requestTimeout, }?: TimeoutFetchMethodOptions): FetchMethod;
+//# sourceMappingURL=createTimeoutFetchMethod.d.ts.map

package/dist/fetch/createTimeoutFetchMethod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTimeoutFetchMethod.d.ts","sourceRoot":"","sources":["../../src/fetch/createTimeoutFetchMethod.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,WAAW,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAA;AAW9F;;GAEG;AACH,MAAM,WAAW,yBAA0B,SAAQ,sBAAsB;IACvE;;;;;;;;;OASG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,0BAA0B,KAAK,IAAI,CAAA;IAEhE;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,wBAAwB,CAAC,EACvC,OAAwB,EACxB,WAAmB,EACnB,gBAAgB,EAChB,cAAwC,GACzC,GAAE,yBAA8B,GAAG,WAAW,CAoB9C"}

package/dist/fetch/createTimeoutFetchMethod.js

@@ -0,0 +1,51 @@
+import { createScopedLogger } from 'logger';
+const logger = createScopedLogger('ApiClient:Timeout');
+/**
+ * Default timeout (in milliseconds) for outgoing requests.
+ *
+ * @internal
+ */
+const DEFAULT_REQUEST_TIMEOUT = 3000;
+/**
+ * Creates a {@link FetchMethod} that aborts requests after a configurable timeout.
+ *
+ * @param options - Configuration options controlling timeout behavior.
+ * @returns A {@link FetchMethod} that enforces a timeout for each request.
+ *
+ * @remarks
+ * When a timeout occurs, the request is aborted using an {@link AbortController}.
+ * If `onRequestTimeout` is not provided, an error is logged by the {@link logger}.
+ *
+ * @example
+ * ```ts
+ * const fetchWithTimeout = createTimeoutFetchMethod({
+ *   apiName: 'Optimization',
+ *   requestTimeout: 5000,
+ *   onRequestTimeout: ({ apiName }) => {
+ *     console.warn(`${apiName} request timed out`)
+ *   },
+ * })
+ *
+ * const response = await fetchWithTimeout('https://example.com', { method: 'GET' })
+ * ```
+ *
+ * @see {@link TimeoutFetchMethodOptions}
+ */
+export function createTimeoutFetchMethod({ apiName = 'Optimization', fetchMethod = fetch, onRequestTimeout, requestTimeout = DEFAULT_REQUEST_TIMEOUT, } = {}) {
+    return async (url, init) => {
+        const controller = new AbortController();
+        const id = setTimeout(() => {
+            if (typeof onRequestTimeout === 'function') {
+                onRequestTimeout({ apiName });
+            }
+            else {
+                logger.error(`Request to "${url.toString()}" timed out`, new Error('Request timeout'));
+            }
+            controller.abort();
+        }, requestTimeout);
+        const response = await fetchMethod(url, { ...init, signal: controller.signal });
+        clearTimeout(id);
+        return response;
+    };
+}
+//# sourceMappingURL=createTimeoutFetchMethod.js.map

package/dist/fetch/createTimeoutFetchMethod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTimeoutFetchMethod.js","sourceRoot":"","sources":["../../src/fetch/createTimeoutFetchMethod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAA;AAG3C,MAAM,MAAM,GAAG,kBAAkB,CAAC,mBAAmB,CAAC,CAAA;AAEtD;;;;GAIG;AACH,MAAM,uBAAuB,GAAG,IAAI,CAAA;AA2BpC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,wBAAwB,CAAC,EACvC,OAAO,GAAG,cAAc,EACxB,WAAW,GAAG,KAAK,EACnB,gBAAgB,EAChB,cAAc,GAAG,uBAAuB,MACX,EAAE;IAC/B,OAAO,KAAK,EAAE,GAAiB,EAAE,IAAiB,EAAE,EAAE;QACpD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;QAExC,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE;YACzB,IAAI,OAAO,gBAAgB,KAAK,UAAU,EAAE,CAAC;gBAC3C,gBAAgB,CAAC,EAAE,OAAO,EAAE,CAAC,CAAA;YAC/B,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,KAAK,CAAC,eAAe,GAAG,CAAC,QAAQ,EAAE,aAAa,EAAE,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC,CAAA;YACxF,CAAC;YAED,UAAU,CAAC,KAAK,EAAE,CAAA;QACpB,CAAC,EAAE,cAAc,CAAC,CAAA;QAElB,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAA;QAE/E,YAAY,CAAC,EAAE,CAAC,CAAA;QAEhB,OAAO,QAAQ,CAAA;IACjB,CAAC,CAAA;AACH,CAAC"}

package/dist/fetch/index.d.ts

@@ -0,0 +1,7 @@
+import Fetch from './Fetch';
+export * from './createProtectedFetchMethod';
+export * from './createRetryFetchMethod';
+export * from './createTimeoutFetchMethod';
+export * from './Fetch';
+export default Fetch;
+//# sourceMappingURL=index.d.ts.map

package/dist/fetch/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fetch/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,SAAS,CAAA;AAE3B,cAAc,8BAA8B,CAAA;AAC5C,cAAc,0BAA0B,CAAA;AACxC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,SAAS,CAAA;AAEvB,eAAe,KAAK,CAAA"}

package/dist/fetch/index.js

@@ -0,0 +1,7 @@
+import Fetch from './Fetch';
+export * from './createProtectedFetchMethod';
+export * from './createRetryFetchMethod';
+export * from './createTimeoutFetchMethod';
+export * from './Fetch';
+export default Fetch;
+//# sourceMappingURL=index.js.map

package/dist/fetch/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/fetch/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,SAAS,CAAA;AAE3B,cAAc,8BAA8B,CAAA;AAC5C,cAAc,0BAA0B,CAAA;AACxC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,SAAS,CAAA;AAEvB,eAAe,KAAK,CAAA"}