@adobe/spacecat-shared-project-engine-client 1.11.0 → 1.12.0

package/README.md

@@ -34,6 +34,10 @@ const { data, error } = await client.GET('/v1/countries');
 - **Retries:** `429` is retried for any method; `5xx`/network errors only for idempotent methods
   (so a POST is never replayed). Backoff is exponential with jitter, honours `Retry-After`, and is
   capped at 20s/attempt. Pass `onRetry` to observe the loop.
+- **Timeouts:** pass `requestTimeoutMs` to bound each attempt — a stalled attempt is aborted via
+  `AbortSignal.timeout` (a per-attempt deadline, combined with any caller `signal`, never
+  replacing it) and, for idempotent methods, retried. Unset (default) ⇒ no client-imposed deadline,
+  so a hung socket blocks until the platform's own limit; set this to bound it.
 - **Shape:** this is a thin factory function rather than the `CLAUDE.md` "class + factory" client
   pattern — the wrapper has no per-instance state or behaviour beyond what `openapi-fetch` already
   provides, so a class would add ceremony without value. The typed surface IS the `openapi-fetch`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-project-engine-client",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Shared modules of the Spacecat Services - Semrush Project Engine client and generated types",
   "type": "module",
   "main": "src/index.js",

package/src/client.js

@@ -44,6 +44,11 @@ import { createRetryingFetch, toTokenGetter } from './internal.js';
  *   retry sleep (`{ attempt, delayMs, method, status?, error? }`), for logging/metrics. A retry
  *   loop is otherwise silent — an operator can't tell "slow upstream" from "stuck in backoff". A
  *   throwing or rejecting hook is swallowed and never affects the request.
+ * @property {number} [requestTimeoutMs] Per-attempt request deadline in ms. When set (> 0), each
+ *   fetch attempt is aborted via `AbortSignal.timeout` after this many ms and — for an idempotent
+ *   method — retried under the retry budget; a caller-supplied `signal` is still honoured
+ *   (combined, not replaced). Unset (the default) ⇒ no client-imposed deadline, so a hung socket
+ *   blocks until the platform's own limit; set this to bound it.
  * @property {typeof globalThis.fetch} [fetch] Injectable fetch (tests, custom agents).
  *   Defaults to the global fetch.
  */
@@ -120,12 +125,37 @@ export function createSerenityProjectEngineApiClient(options) {
     maxRetries = 2,
     retryBaseDelayMs = 200,
     onRetry,
+    requestTimeoutMs,
     fetch: injectedFetch = globalThis.fetch,
   } = options;
 
+  // Fail fast on a misconfigured timeout rather than silently disabling it: a NaN/negative value
+  // would no-op in withDeadline (leaving the caller unprotected), and Infinity would reach
+  // AbortSignal.timeout. Mirrors the defensive toTokenGetter/resolveBaseUrl guards below.
+  if (
+    requestTimeoutMs !== undefined
+    && (typeof requestTimeoutMs !== 'number'
+      || !Number.isFinite(requestTimeoutMs)
+      || requestTimeoutMs <= 0)
+  ) {
+    throw new Error(
+      // Report numbers verbatim so NaN/Infinity read as themselves (JSON.stringify would render
+      // both as "null"); stringify other types so a bad string is visibly quoted.
+      `Project Engine client: requestTimeoutMs must be a positive finite number of ms, got ${
+        typeof requestTimeoutMs === 'number' ? requestTimeoutMs : JSON.stringify(requestTimeoutMs)
+      }`,
+    );
+  }
+
   const client = createClient({
     baseUrl: resolveBaseUrl(baseUrl),
-    fetch: createRetryingFetch(injectedFetch, maxRetries, retryBaseDelayMs, onRetry),
+    fetch: createRetryingFetch(
+      injectedFetch,
+      maxRetries,
+      retryBaseDelayMs,
+      onRetry,
+      requestTimeoutMs,
+    ),
   });
   // Auth runs as openapi-fetch middleware, so the token getter resolves once per logical request
   // and that token is reused across the request's retries (the retry layer clones the same Request

package/src/index.d.ts

@@ -52,6 +52,13 @@ export interface SerenityProjectEngineApiClientOptions {
     status?: number;
     error?: Error;
   }) => void | Promise<void>;
+  /**
+   * Per-attempt request deadline in ms. When set (> 0), each fetch attempt is aborted via
+   * `AbortSignal.timeout` after this many ms (and retried for idempotent methods under the retry
+   * budget); any caller-supplied `signal` is combined with it, never replaced. Unset ⇒ no
+   * client-imposed deadline.
+   */
+  requestTimeoutMs?: number;
   /** Injectable fetch (tests, custom agents). Defaults to the global fetch. */
   fetch?: typeof globalThis.fetch;
 }

package/src/internal.js

@@ -130,7 +130,8 @@ export function nextRetryDelayMs(completedAttempt, baseDelayMs, response) {
  * @property {number} delayMs the wait before this retry
  * @property {string} method the HTTP method
  * @property {number} [status] the retryable response status that triggered the retry, if any
- * @property {Error} [error] the network error that triggered the retry, if any
+ * @property {Error} [error] the error that triggered the retry, if any — a network error, or a
+ *   per-attempt `AbortSignal.timeout` `TimeoutError` (both are `instanceof Error`)
  */
 
 /**
@@ -164,9 +165,32 @@ function notifyRetry(onRetry, info) {
  * @returns {void | Promise<void>} may be async; the return is not awaited (fire-and-forget)
  */
 
+/**
+ * Builds the per-attempt fetch `init` for {@link createRetryingFetch}. When `requestTimeoutMs`
+ * is a positive number, each attempt gets a FRESH `AbortSignal.timeout(requestTimeoutMs)` (the
+ * retry layer calls the underlying fetch once per attempt, so this is a per-attempt deadline, not
+ * a single budget spanning the whole retry loop) — combined with, never replacing, any
+ * caller-supplied signal via `AbortSignal.any`, so a caller abort and the deadline each still
+ * cancel the request. With no timeout configured the caller's `init` is returned untouched, so a
+ * caller signal continues to flow through natively.
+ * @param {RequestInit} [init]
+ * @param {AbortSignal} [callerSignal]
+ * @param {number} [requestTimeoutMs]
+ * @returns {RequestInit | undefined}
+ */
+export function withDeadline(init, callerSignal, requestTimeoutMs) {
+  if (!requestTimeoutMs || requestTimeoutMs <= 0) {
+    return init;
+  }
+  const timeoutSignal = AbortSignal.timeout(requestTimeoutMs);
+  const signal = callerSignal ? AbortSignal.any([callerSignal, timeoutSignal]) : timeoutSignal;
+  return { ...init, signal };
+}
+
 /**
  * Wraps a fetch with bounded exponential-backoff retries. Retryable statuses follow
- * {@link isRetryableStatus}; thrown network errors are retried only for idempotent methods.
+ * {@link isRetryableStatus}; thrown errors (a network error, or a per-attempt timeout) are
+ * retried only for idempotent methods.
  * The wait between attempts is {@link nextRetryDelayMs} — jittered exponential backoff that also
  * honours a `Retry-After` header. After exhausting retries it returns the last retryable response
  * (so the caller still sees e.g. the final 503) or rethrows the last network error.
@@ -180,9 +204,12 @@ function notifyRetry(onRetry, info) {
  * @param {number} maxRetries
  * @param {number} baseDelayMs
  * @param {OnRetry} [onRetry] optional best-effort retry-observability hook
+ * @param {number} [requestTimeoutMs] optional per-attempt deadline in ms; when > 0 each attempt is
+ *   aborted via `AbortSignal.timeout` (combined with any caller signal) and, for idempotent
+ *   methods, retried under the retry budget. Unset ⇒ no client-imposed deadline.
  * @returns {typeof globalThis.fetch}
  */
-export function createRetryingFetch(baseFetch, maxRetries, baseDelayMs, onRetry) {
+export function createRetryingFetch(baseFetch, maxRetries, baseDelayMs, onRetry, requestTimeoutMs) {
   return async function retryingFetch(input, init) {
     const method = methodOf(input, init);
     // Floor at 0: a negative maxRetries would skip the loop entirely, leaving both lastResponse
@@ -196,6 +223,9 @@ export function createRetryingFetch(baseFetch, maxRetries, baseDelayMs, onRetry)
     // token is resolved per request, not per attempt; with the ceiling above the whole loop is
     // bounded well under an IMS token's lifetime, so mid-loop expiry is a non-issue.
     const forAttempt = () => (input instanceof Request ? input.clone() : input);
+    // Resolve any caller-supplied AbortSignal once. openapi-fetch calls us with a Request whose
+    // own `.signal` reflects a caller `signal` option; a bare-URL fetch may carry it on `init`.
+    const callerSignal = init?.signal ?? (input instanceof Request ? input.signal : undefined);
     let lastResponse;
     let lastError;
     let nextDelayMs = 0;
@@ -215,8 +245,9 @@ export function createRetryingFetch(baseFetch, maxRetries, baseDelayMs, onRetry)
         await sleep(nextDelayMs);
       }
       try {
+        const attemptInit = withDeadline(init, callerSignal, requestTimeoutMs);
         // eslint-disable-next-line no-await-in-loop
-        const response = await baseFetch(forAttempt(), init);
+        const response = await baseFetch(forAttempt(), attemptInit);
         if (!isRetryableStatus(method, response.status)) {
           return response;
         }