@adobe/spacecat-shared-project-engine-client 1.10.1 → 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`
@@ -46,8 +50,18 @@ version control. Semrush only provides the file (no endpoint access in the near
 it's **Swagger 2.0** (no v3/v3.1 on offer). The vendored file is **never edited**; where it
 diverges from the live API, a generation-time overlay corrects the converted artifact instead (see
 [Spec corrections](#spec-corrections)). Refresh is **manual**: drop in the newer file, re-run
-`npm run generate`, and review the diff. There is no automated drift detection while endpoint
-access is restricted.
+`npm run generate`, and review the diff. A committed checksum lock
+(`spec/projectengine_swagger_public.yaml.sha256`) is verified by `npm run spec:verify` (wired into
+`pretest`, so CI enforces it): any re-vendor of the spec fails the build until the hash is
+explicitly regenerated with `npm run spec:lock` and reviewed. A true live-drift contract test
+against Semrush remains blocked on endpoint access.
+
+Both scripts use a **package-root-relative** path and assume the working directory is this
+package root — always invoke them via `npm run spec:verify` / `npm run spec:lock`, which npm
+runs from the package root, rather than calling `shasum -c` by hand from the monorepo root or a
+subdirectory (that yields a confusing "no such file" error). They also assume `shasum` (Perl,
+present on macOS and the `ubuntu-latest` CI runner); minimal images such as Alpine ship
+`sha256sum` instead and would need the scripts adjusted.
 
 ## Pipeline
 
@@ -144,6 +158,7 @@ Stateful endpoints (backed by the store):
 | `POST /v2/workspaces/{id}/projects/{project_id}/aio/prompts/tagged` | create prompts grouped by tag name |
 | `POST /v2/workspaces/{id}/projects/{project_id}/aio/prompts/by_tags` | list prompts (empty `tag_ids` lists all; otherwise OR-filter) |
 | `DELETE /v2/workspaces/{id}/projects/{project_id}/aio/prompts` | batch-delete prompts by id |
+| `POST /v2/workspaces/{id}/projects/{project_id}/aio/prompts/{prompt_id}/rename` | in-place text edit (id stable; `409` on a sibling-text collision; `is_updated` mirrors the live layer) |
 
 ### Test control routes (not part of the Project Engine API)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-project-engine-client",
-  "version": "1.10.1",
+  "version": "1.12.0",
   "description": "Shared modules of the Spacecat Services - Semrush Project Engine client and generated types",
   "type": "module",
   "main": "src/index.js",
@@ -20,12 +20,15 @@
     "npm": ">=10.9.0 <12.0.0"
   },
   "scripts": {
+    "pretest": "npm run spec:verify",
     "test": "c8 mocha",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
     "clean": "rm -rf node_modules build .counterfact",
     "spec:convert": "mkdir -p build && swagger2openapi spec/projectengine_swagger_public.yaml --patch --outfile build/openapi3.json",
     "spec:overlay": "node scripts/apply-overlay.mjs",
+    "spec:verify": "shasum -a 256 -c spec/projectengine_swagger_public.yaml.sha256",
+    "spec:lock": "shasum -a 256 spec/projectengine_swagger_public.yaml > spec/projectengine_swagger_public.yaml.sha256",
     "generate:ts": "openapi-typescript build/openapi3.json --output src/generated/types.ts",
     "generate:pydantic": "datamodel-codegen --input build/openapi3.json --input-file-type openapi --output python/serenity_project_engine/ --output-model-type pydantic_v2.BaseModel",
     "generate": "npm run spec:convert && npm run spec:overlay && npm run generate:ts && npm run generate:pydantic",

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/generated/types.ts

@@ -2289,7 +2289,7 @@ export interface components {
             replace?: boolean;
         };
         "model.RenamePromptRequest": {
-            new_name?: string;
+            new_name?: string | null;
         };
         "model.RenamePromptResponse": {
             id?: string;
@@ -7723,6 +7723,15 @@ export interface operations {
                     "application/json": components["schemas"]["http_server.BasicResponse"];
                 };
             };
+            /** @description Conflict */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["http_server.BasicResponse"];
+                };
+            };
             /** @description Internal Server Error */
             500: {
                 headers: {

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;
         }