@adobe/spacecat-shared-project-engine-client 1.11.0 → 1.13.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.13.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

@@ -10,7 +10,8 @@
  * governing permissions and limitations under the License.
  */
 
-import type { Client } from 'openapi-fetch';
+import type { Client, FetchResponse, MaybeOptionalInit, MediaType } from 'openapi-fetch';
+import type { RequiredKeysOf } from 'openapi-typescript-helpers';
 import type { paths, components } from './generated/types.js';
 
 /** Supplies the caller's IMS JWT — forwarded verbatim, never minted or exchanged. */
@@ -52,6 +53,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;
 }
@@ -66,5 +74,284 @@ export declare function createSerenityProjectEngineApiClient(
   options: SerenityProjectEngineApiClientOptions,
 ): SerenityProjectEngineApiClient;
 
+// ───────────────────────────────────────────────────────────────────────────
+// Intent-named facade (transport) over the raw client.
+//
+// The three helpers below derive every facade method's parameter and return type
+// straight from the generated `paths` contract, so the surface stays strictly
+// in-spec and never degrades to `any`. They are internal to this declaration.
+// ───────────────────────────────────────────────────────────────────────────
+
+/**
+ * The openapi-fetch `init` argument (params.path/query, body) accepted for a given
+ * path `P` + HTTP method `M`, derived from the generated contract.
+ */
+type TransportInit<P extends keyof paths, M extends keyof paths[P]> = MaybeOptionalInit<
+  paths[P],
+  M
+>;
+
+/**
+ * Mirror of openapi-fetch's own (unexported) `InitParam`: the `init` argument is
+ * OPTIONAL when nothing in it is required (no path/query params, no required body),
+ * and REQUIRED otherwise — so `listLanguages()` needs no argument while
+ * `createProject({ params, body })` enforces its params + body at the call site.
+ */
+type TransportInitParam<Init> = RequiredKeysOf<Init> extends never
+  ? [init?: Init]
+  : [init: Init];
+
+/**
+ * The value a facade method resolves with: the parsed 2xx body for path `P` +
+ * method `M`, or `null` for an empty body (e.g. a 204 / empty-body ack). Non-2xx
+ * responses never resolve — they throw at the single `unwrap` error seam.
+ */
+type TransportData<P extends keyof paths, M extends keyof paths[P]> =
+  | NonNullable<FetchResponse<paths[P][M], TransportInit<P, M>, MediaType>['data']>
+  | null;
+
+/**
+ * Intent-named facade over {@link SerenityProjectEngineApiClient}. Wraps the 28 in-spec
+ * Project Engine operations spacecat-api-service consumes behind verb+resource methods, so
+ * consumers depend on this seam rather than the raw client's literal path strings. Each method
+ * is THIN: it forwards the caller's openapi-fetch `init` to the underlying client and resolves
+ * with the unwrapped 2xx body (or throws on a non-2xx / network error at a single seam). No
+ * caching, redaction, error→HTTP translation, or composite methods — all consumer-owned per
+ * ADR-0001. The remaining generated operations stay reachable via the raw client.
+ */
+export interface SerenityProjectEngineTransport {
+  /** GET /v1/languages — projects-admin-list-languages */
+  listLanguages(
+    ...init: TransportInitParam<TransportInit<'/v1/languages', 'get'>>
+  ): Promise<TransportData<'/v1/languages', 'get'>>;
+  /** GET /v1/ai_models — ai-list-global-models */
+  listGlobalAiModels(
+    ...init: TransportInitParam<TransportInit<'/v1/ai_models', 'get'>>
+  ): Promise<TransportData<'/v1/ai_models', 'get'>>;
+
+  /** GET /v1/workspaces/{id}/projects — projects-list-projects */
+  listProjects(
+    ...init: TransportInitParam<TransportInit<'/v1/workspaces/{id}/projects', 'get'>>
+  ): Promise<TransportData<'/v1/workspaces/{id}/projects', 'get'>>;
+  /** POST /v1/workspaces/{id}/projects — projects-post-project */
+  createProject(
+    ...init: TransportInitParam<TransportInit<'/v1/workspaces/{id}/projects', 'post'>>
+  ): Promise<TransportData<'/v1/workspaces/{id}/projects', 'post'>>;
+  /** GET /v1/workspaces/{id}/projects/{project_id} — projects-get-project */
+  getProject(
+    ...init: TransportInitParam<TransportInit<'/v1/workspaces/{id}/projects/{project_id}', 'get'>>
+  ): Promise<TransportData<'/v1/workspaces/{id}/projects/{project_id}', 'get'>>;
+  /** PATCH /v1/workspaces/{id}/projects/{project_id} — projects-patch-project */
+  updateProject(
+    ...init: TransportInitParam<TransportInit<'/v1/workspaces/{id}/projects/{project_id}', 'patch'>>
+  ): Promise<TransportData<'/v1/workspaces/{id}/projects/{project_id}', 'patch'>>;
+  /** DELETE /v1/workspaces/{id}/projects/{project_id} — projects-delete-project */
+  deleteProject(
+    ...init: TransportInitParam<
+      TransportInit<'/v1/workspaces/{id}/projects/{project_id}', 'delete'>
+    >
+  ): Promise<TransportData<'/v1/workspaces/{id}/projects/{project_id}', 'delete'>>;
+  /** POST /v1/workspaces/{id}/projects/{project_id}/publish — projects-publish-project */
+  publishProject(
+    ...init: TransportInitParam<
+      TransportInit<'/v1/workspaces/{id}/projects/{project_id}/publish', 'post'>
+    >
+  ): Promise<TransportData<'/v1/workspaces/{id}/projects/{project_id}/publish', 'post'>>;
+
+  /** GET /v1/workspaces/{id}/projects/{project_id}/ai_models — ai-list-models */
+  listAiModels(
+    ...init: TransportInitParam<
+      TransportInit<'/v1/workspaces/{id}/projects/{project_id}/ai_models', 'get'>
+    >
+  ): Promise<TransportData<'/v1/workspaces/{id}/projects/{project_id}/ai_models', 'get'>>;
+  /** DELETE /v1/workspaces/{id}/projects/{project_id}/ai_models — ai-delete-models */
+  deleteAiModels(
+    ...init: TransportInitParam<
+      TransportInit<'/v1/workspaces/{id}/projects/{project_id}/ai_models', 'delete'>
+    >
+  ): Promise<TransportData<'/v1/workspaces/{id}/projects/{project_id}/ai_models', 'delete'>>;
+  /** GET /v1/workspaces/{id}/projects/{project_id}/ai_models/benchmarks — ai-list-benchmarks */
+  listBenchmarks(
+    ...init: TransportInitParam<
+      TransportInit<'/v1/workspaces/{id}/projects/{project_id}/ai_models/benchmarks', 'get'>
+    >
+  ): Promise<
+    TransportData<'/v1/workspaces/{id}/projects/{project_id}/ai_models/benchmarks', 'get'>
+  >;
+  /** DELETE /v1/workspaces/{id}/projects/{project_id}/ai_models/benchmarks — ai-delete-benchmarks */
+  deleteBenchmarks(
+    ...init: TransportInitParam<
+      TransportInit<'/v1/workspaces/{id}/projects/{project_id}/ai_models/benchmarks', 'delete'>
+    >
+  ): Promise<
+    TransportData<'/v1/workspaces/{id}/projects/{project_id}/ai_models/benchmarks', 'delete'>
+  >;
+  /**
+   * PUT /v1/workspaces/{id}/projects/{project_id}/ai_models/benchmarks/{benchmark_id}
+   * — ai-update-benchmark
+   */
+  updateBenchmark(
+    ...init: TransportInitParam<
+      TransportInit<
+        '/v1/workspaces/{id}/projects/{project_id}/ai_models/benchmarks/{benchmark_id}',
+        'put'
+      >
+    >
+  ): Promise<
+    TransportData<
+      '/v1/workspaces/{id}/projects/{project_id}/ai_models/benchmarks/{benchmark_id}',
+      'put'
+    >
+  >;
+  /** PUT /v1/workspaces/{id}/projects/{project_id}/ci/competitors — ci-update-competitors */
+  updateCompetitors(
+    ...init: TransportInitParam<
+      TransportInit<'/v1/workspaces/{id}/projects/{project_id}/ci/competitors', 'put'>
+    >
+  ): Promise<TransportData<'/v1/workspaces/{id}/projects/{project_id}/ci/competitors', 'put'>>;
+
+  /** POST /v2/workspaces/{id}/projects/{project_id}/ai_models — aio-project-create-model */
+  createAioModel(
+    ...init: TransportInitParam<
+      TransportInit<'/v2/workspaces/{id}/projects/{project_id}/ai_models', 'post'>
+    >
+  ): Promise<TransportData<'/v2/workspaces/{id}/projects/{project_id}/ai_models', 'post'>>;
+  /** POST /v2/workspaces/{id}/projects/{project_id}/ai_models/benchmarks — ai-create-benchmarks-v2 */
+  createBenchmarks(
+    ...init: TransportInitParam<
+      TransportInit<'/v2/workspaces/{id}/projects/{project_id}/ai_models/benchmarks', 'post'>
+    >
+  ): Promise<
+    TransportData<'/v2/workspaces/{id}/projects/{project_id}/ai_models/benchmarks', 'post'>
+  >;
+
+  /**
+   * GET /v2/workspaces/{id}/projects/{project_id}/aio/benchmarks/{benchmark_id}/brand_urls
+   * — aio-list-brand-urls
+   */
+  listBrandUrls(
+    ...init: TransportInitParam<
+      TransportInit<
+        '/v2/workspaces/{id}/projects/{project_id}/aio/benchmarks/{benchmark_id}/brand_urls',
+        'get'
+      >
+    >
+  ): Promise<
+    TransportData<
+      '/v2/workspaces/{id}/projects/{project_id}/aio/benchmarks/{benchmark_id}/brand_urls',
+      'get'
+    >
+  >;
+  /**
+   * POST /v2/workspaces/{id}/projects/{project_id}/aio/benchmarks/{benchmark_id}/brand_urls
+   * — aio-create-brand-urls
+   */
+  createBrandUrls(
+    ...init: TransportInitParam<
+      TransportInit<
+        '/v2/workspaces/{id}/projects/{project_id}/aio/benchmarks/{benchmark_id}/brand_urls',
+        'post'
+      >
+    >
+  ): Promise<
+    TransportData<
+      '/v2/workspaces/{id}/projects/{project_id}/aio/benchmarks/{benchmark_id}/brand_urls',
+      'post'
+    >
+  >;
+  /**
+   * DELETE /v2/workspaces/{id}/projects/{project_id}/aio/benchmarks/{benchmark_id}/brand_urls
+   * — aio-delete-brand-urls
+   */
+  deleteBrandUrls(
+    ...init: TransportInitParam<
+      TransportInit<
+        '/v2/workspaces/{id}/projects/{project_id}/aio/benchmarks/{benchmark_id}/brand_urls',
+        'delete'
+      >
+    >
+  ): Promise<
+    TransportData<
+      '/v2/workspaces/{id}/projects/{project_id}/aio/benchmarks/{benchmark_id}/brand_urls',
+      'delete'
+    >
+  >;
+
+  /**
+   * GET /v2/workspaces/{id}/projects/{project_id}/aio/init_status
+   * — aio-get-project-init-status-v2
+   */
+  getProjectInitStatus(
+    ...init: TransportInitParam<
+      TransportInit<'/v2/workspaces/{id}/projects/{project_id}/aio/init_status', 'get'>
+    >
+  ): Promise<TransportData<'/v2/workspaces/{id}/projects/{project_id}/aio/init_status', 'get'>>;
+  /** POST /v2/workspaces/{id}/projects/{project_id}/aio/prompts — aio-create-prompt-v2 */
+  createPrompts(
+    ...init: TransportInitParam<
+      TransportInit<'/v2/workspaces/{id}/projects/{project_id}/aio/prompts', 'post'>
+    >
+  ): Promise<TransportData<'/v2/workspaces/{id}/projects/{project_id}/aio/prompts', 'post'>>;
+  /** DELETE /v2/workspaces/{id}/projects/{project_id}/aio/prompts — aio-delete-prompt-by-ids-v2 */
+  deletePromptsByIds(
+    ...init: TransportInitParam<
+      TransportInit<'/v2/workspaces/{id}/projects/{project_id}/aio/prompts', 'delete'>
+    >
+  ): Promise<TransportData<'/v2/workspaces/{id}/projects/{project_id}/aio/prompts', 'delete'>>;
+  /**
+   * POST /v2/workspaces/{id}/projects/{project_id}/aio/prompts/by_tags
+   * — aio-list-prompts-by-tag-ids
+   */
+  listPromptsByTagIds(
+    ...init: TransportInitParam<
+      TransportInit<'/v2/workspaces/{id}/projects/{project_id}/aio/prompts/by_tags', 'post'>
+    >
+  ): Promise<TransportData<'/v2/workspaces/{id}/projects/{project_id}/aio/prompts/by_tags', 'post'>>;
+  /** PUT /v2/workspaces/{id}/projects/{project_id}/aio/prompts/tags — aio-update-prompts-batch */
+  updatePromptTags(
+    ...init: TransportInitParam<
+      TransportInit<'/v2/workspaces/{id}/projects/{project_id}/aio/prompts/tags', 'put'>
+    >
+  ): Promise<TransportData<'/v2/workspaces/{id}/projects/{project_id}/aio/prompts/tags', 'put'>>;
+  /**
+   * POST /v2/workspaces/{id}/projects/{project_id}/aio/prompts/{prompt_id}/rename
+   * — aio-rename-prompt
+   */
+  renamePrompt(
+    ...init: TransportInitParam<
+      TransportInit<'/v2/workspaces/{id}/projects/{project_id}/aio/prompts/{prompt_id}/rename', 'post'>
+    >
+  ): Promise<
+    TransportData<'/v2/workspaces/{id}/projects/{project_id}/aio/prompts/{prompt_id}/rename', 'post'>
+  >;
+  /** GET /v2/workspaces/{id}/projects/{project_id}/aio/tags — aio-get-project-tags */
+  listProjectTags(
+    ...init: TransportInitParam<
+      TransportInit<'/v2/workspaces/{id}/projects/{project_id}/aio/tags', 'get'>
+    >
+  ): Promise<TransportData<'/v2/workspaces/{id}/projects/{project_id}/aio/tags', 'get'>>;
+  /** POST /v2/workspaces/{id}/projects/{project_id}/aio/tags — aio-create-project-tags */
+  createProjectTags(
+    ...init: TransportInitParam<
+      TransportInit<'/v2/workspaces/{id}/projects/{project_id}/aio/tags', 'post'>
+    >
+  ): Promise<TransportData<'/v2/workspaces/{id}/projects/{project_id}/aio/tags', 'post'>>;
+  /** PATCH /v2/workspaces/{id}/projects/{project_id}/aio/tags/{tag_id} — aio-update-tag */
+  updateProjectTag(
+    ...init: TransportInitParam<
+      TransportInit<'/v2/workspaces/{id}/projects/{project_id}/aio/tags/{tag_id}', 'patch'>
+    >
+  ): Promise<TransportData<'/v2/workspaces/{id}/projects/{project_id}/aio/tags/{tag_id}', 'patch'>>;
+}
+
+/**
+ * Builds the {@link SerenityProjectEngineTransport} facade. Takes the SAME options as
+ * {@link createSerenityProjectEngineApiClient} (it builds that client internally and adds no
+ * options of its own).
+ */
+export declare function createSerenityProjectEngineTransport(
+  options: SerenityProjectEngineApiClientOptions,
+): SerenityProjectEngineTransport;
+
 // Re-export the generated contract types for consumers that want them directly.
 export type { paths, components };

package/src/index.js

@@ -13,3 +13,4 @@
 // @ts-check
 
 export { createSerenityProjectEngineApiClient } from './client.js';
+export { createSerenityProjectEngineTransport } from './rest-transport.js';

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

package/src/rest-transport.js

@@ -0,0 +1,229 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+// @ts-check
+
+import { createSerenityProjectEngineApiClient } from './client.js';
+
+/**
+ * @typedef {import('./client.js').SerenityProjectEngineApiClientOptions}
+ *   SerenityProjectEngineApiClientOptions
+ */
+
+/**
+ * Intent-named facade over the raw {@link createSerenityProjectEngineApiClient} openapi-fetch
+ * client. It wraps ONLY the 28 in-spec Project Engine operations that spacecat-api-service
+ * consumes, behind verb+resource method names, so consumers depend on this seam rather than the
+ * raw client and its literal path strings. Each method is THIN: it forwards the caller's
+ * openapi-fetch `init` (params.path/query, body) to `client.<METHOD>('<literal path>', init)` and
+ * routes the result through the single {@link unwrap} error seam. There is deliberately NO caching,
+ * redaction, error→HTTP translation, or composite/convenience method here — all consumer-owned per
+ * ADR-0001. The remaining generated operations stay reachable via the raw client; add a facade
+ * method only when a real second consumer needs one.
+ *
+ * @param {SerenityProjectEngineApiClientOptions} options The SAME options as the raw client — the
+ *   facade adds none of its own. Builds the underlying client via
+ *   {@link createSerenityProjectEngineApiClient}.
+ * @returns {import('./index.js').SerenityProjectEngineTransport}
+ */
+export function createSerenityProjectEngineTransport(options) {
+  const client = createSerenityProjectEngineApiClient(options);
+
+  /**
+   * The SINGLE seam where a failed call becomes a throw. It awaits the openapi-fetch result
+   * promise here (so a network/timeout rejection also flows through this one point), and on a
+   * non-2xx response throws. The typed client never throws on an HTTP error — it resolves to
+   * `{ data, error, response }` with the parsed error body in `error` — so a non-2xx is turned
+   * into a throw here; a 2xx returns the parsed body (or null for an empty body).
+   *
+   * `status`, `method`, and the normalized `body` are computed locally at this site FIRST so the
+   * follow-up ticket LLMO-5978 can swap ONLY the `new Error(...)` line below for
+   * `new ProjectEngineApiError(status, method, body)` without reshaping anything else here.
+   *
+   * @template T
+   * @param {string} method the HTTP method, for the error message
+   * @param {Promise<{ data?: T, error?: unknown, response: Response }>} resultPromise the pending
+   *   openapi-fetch result
+   * @returns {Promise<NonNullable<T> | null>} the parsed success body, or null for an empty body
+   *   (an empty-body operation resolves with null, never undefined)
+   */
+  async function unwrap(method, resultPromise) {
+    const { data, error, response } = await resultPromise;
+    if (!response.ok) {
+      const { status } = response;
+      // openapi-fetch surfaces an empty error body as '' (not undefined); normalise it to null.
+      const rawBody = error ?? data ?? null;
+      // `body` is computed here but not consumed by the plain Error below. LLMO-5978 swaps ONLY
+      // the `new Error(...)` line for `new ProjectEngineApiError(status, method, body)` — status,
+      // method, and this normalized body are all already in scope, so nothing else here changes.
+      // eslint-disable-next-line no-unused-vars
+      const body = rawBody === '' ? null : rawBody;
+      // Message deliberately omits the request URL: it embeds path-param ids (workspace/
+      // project/etc.) that error-reporter and log consumers should not receive by default.
+      throw new Error(`Project Engine ${method} failed: ${status}`);
+    }
+    return data ?? null;
+  }
+
+  return {
+    // ─── /v1 catalog ────────────────────────────────────────────────────────
+    /** GET /v1/languages — projects-admin-list-languages */
+    listLanguages(init) {
+      return unwrap('GET', client.GET('/v1/languages', init));
+    },
+    /** GET /v1/ai_models — ai-list-global-models */
+    listGlobalAiModels(init) {
+      return unwrap('GET', client.GET('/v1/ai_models', init));
+    },
+
+    // ─── /v1 projects ───────────────────────────────────────────────────────
+    /** GET /v1/workspaces/{id}/projects — projects-list-projects */
+    listProjects(init) {
+      return unwrap('GET', client.GET('/v1/workspaces/{id}/projects', init));
+    },
+    /** POST /v1/workspaces/{id}/projects — projects-post-project */
+    createProject(init) {
+      return unwrap('POST', client.POST('/v1/workspaces/{id}/projects', init));
+    },
+    /** GET /v1/workspaces/{id}/projects/{project_id} — projects-get-project */
+    getProject(init) {
+      return unwrap('GET', client.GET('/v1/workspaces/{id}/projects/{project_id}', init));
+    },
+    /** PATCH /v1/workspaces/{id}/projects/{project_id} — projects-patch-project */
+    updateProject(init) {
+      return unwrap('PATCH', client.PATCH('/v1/workspaces/{id}/projects/{project_id}', init));
+    },
+    /** DELETE /v1/workspaces/{id}/projects/{project_id} — projects-delete-project */
+    deleteProject(init) {
+      return unwrap('DELETE', client.DELETE('/v1/workspaces/{id}/projects/{project_id}', init));
+    },
+    /** POST /v1/workspaces/{id}/projects/{project_id}/publish — projects-publish-project */
+    publishProject(init) {
+      return unwrap('POST', client.POST('/v1/workspaces/{id}/projects/{project_id}/publish', init));
+    },
+
+    // ─── /v1 AI models + benchmarks ───────────────────────────────────────────
+    /** GET /v1/workspaces/{id}/projects/{project_id}/ai_models — ai-list-models */
+    listAiModels(init) {
+      return unwrap('GET', client.GET('/v1/workspaces/{id}/projects/{project_id}/ai_models', init));
+    },
+    /** DELETE /v1/workspaces/{id}/projects/{project_id}/ai_models — ai-delete-models */
+    deleteAiModels(init) {
+      return unwrap('DELETE', client.DELETE('/v1/workspaces/{id}/projects/{project_id}/ai_models', init));
+    },
+    /** GET /v1/workspaces/{id}/projects/{project_id}/ai_models/benchmarks — ai-list-benchmarks */
+    listBenchmarks(init) {
+      return unwrap('GET', client.GET('/v1/workspaces/{id}/projects/{project_id}/ai_models/benchmarks', init));
+    },
+    /**
+     * DELETE /v1/workspaces/{id}/projects/{project_id}/ai_models/benchmarks — ai-delete-benchmarks
+     */
+    deleteBenchmarks(init) {
+      return unwrap('DELETE', client.DELETE('/v1/workspaces/{id}/projects/{project_id}/ai_models/benchmarks', init));
+    },
+    /**
+     * PUT /v1/workspaces/{id}/projects/{project_id}/ai_models/benchmarks/{benchmark_id}
+     * — ai-update-benchmark
+     */
+    updateBenchmark(init) {
+      return unwrap('PUT', client.PUT('/v1/workspaces/{id}/projects/{project_id}/ai_models/benchmarks/{benchmark_id}', init));
+    },
+    /** PUT /v1/workspaces/{id}/projects/{project_id}/ci/competitors — ci-update-competitors */
+    updateCompetitors(init) {
+      return unwrap('PUT', client.PUT('/v1/workspaces/{id}/projects/{project_id}/ci/competitors', init));
+    },
+
+    // ─── /v2 AI models + benchmarks ───────────────────────────────────────────
+    /** POST /v2/workspaces/{id}/projects/{project_id}/ai_models — aio-project-create-model */
+    createAioModel(init) {
+      return unwrap('POST', client.POST('/v2/workspaces/{id}/projects/{project_id}/ai_models', init));
+    },
+    /**
+     * POST /v2/workspaces/{id}/projects/{project_id}/ai_models/benchmarks — ai-create-benchmarks-v2
+     */
+    createBenchmarks(init) {
+      return unwrap('POST', client.POST('/v2/workspaces/{id}/projects/{project_id}/ai_models/benchmarks', init));
+    },
+
+    // ─── /v2 brand URLs ───────────────────────────────────────────────────────
+    /**
+     * GET /v2/workspaces/{id}/projects/{project_id}/aio/benchmarks/{benchmark_id}/brand_urls
+     * — aio-list-brand-urls
+     */
+    listBrandUrls(init) {
+      return unwrap('GET', client.GET('/v2/workspaces/{id}/projects/{project_id}/aio/benchmarks/{benchmark_id}/brand_urls', init));
+    },
+    /**
+     * POST /v2/workspaces/{id}/projects/{project_id}/aio/benchmarks/{benchmark_id}/brand_urls
+     * — aio-create-brand-urls
+     */
+    createBrandUrls(init) {
+      return unwrap('POST', client.POST('/v2/workspaces/{id}/projects/{project_id}/aio/benchmarks/{benchmark_id}/brand_urls', init));
+    },
+    /**
+     * DELETE /v2/workspaces/{id}/projects/{project_id}/aio/benchmarks/{benchmark_id}/brand_urls
+     * — aio-delete-brand-urls
+     */
+    deleteBrandUrls(init) {
+      return unwrap('DELETE', client.DELETE('/v2/workspaces/{id}/projects/{project_id}/aio/benchmarks/{benchmark_id}/brand_urls', init));
+    },
+
+    // ─── /v2 AIO project state, prompts, tags ─────────────────────────────────
+    /**
+     * GET /v2/workspaces/{id}/projects/{project_id}/aio/init_status
+     * — aio-get-project-init-status-v2
+     */
+    getProjectInitStatus(init) {
+      return unwrap('GET', client.GET('/v2/workspaces/{id}/projects/{project_id}/aio/init_status', init));
+    },
+    /** POST /v2/workspaces/{id}/projects/{project_id}/aio/prompts — aio-create-prompt-v2 */
+    createPrompts(init) {
+      return unwrap('POST', client.POST('/v2/workspaces/{id}/projects/{project_id}/aio/prompts', init));
+    },
+    /**
+     * DELETE /v2/workspaces/{id}/projects/{project_id}/aio/prompts — aio-delete-prompt-by-ids-v2
+     */
+    deletePromptsByIds(init) {
+      return unwrap('DELETE', client.DELETE('/v2/workspaces/{id}/projects/{project_id}/aio/prompts', init));
+    },
+    /**
+     * POST /v2/workspaces/{id}/projects/{project_id}/aio/prompts/by_tags
+     * — aio-list-prompts-by-tag-ids
+     */
+    listPromptsByTagIds(init) {
+      return unwrap('POST', client.POST('/v2/workspaces/{id}/projects/{project_id}/aio/prompts/by_tags', init));
+    },
+    /** PUT /v2/workspaces/{id}/projects/{project_id}/aio/prompts/tags — aio-update-prompts-batch */
+    updatePromptTags(init) {
+      return unwrap('PUT', client.PUT('/v2/workspaces/{id}/projects/{project_id}/aio/prompts/tags', init));
+    },
+    /**
+     * POST /v2/workspaces/{id}/projects/{project_id}/aio/prompts/{prompt_id}/rename
+     * — aio-rename-prompt
+     */
+    renamePrompt(init) {
+      return unwrap('POST', client.POST('/v2/workspaces/{id}/projects/{project_id}/aio/prompts/{prompt_id}/rename', init));
+    },
+    /** GET /v2/workspaces/{id}/projects/{project_id}/aio/tags — aio-get-project-tags */
+    listProjectTags(init) {
+      return unwrap('GET', client.GET('/v2/workspaces/{id}/projects/{project_id}/aio/tags', init));
+    },
+    /** POST /v2/workspaces/{id}/projects/{project_id}/aio/tags — aio-create-project-tags */
+    createProjectTags(init) {
+      return unwrap('POST', client.POST('/v2/workspaces/{id}/projects/{project_id}/aio/tags', init));
+    },
+    /** PATCH /v2/workspaces/{id}/projects/{project_id}/aio/tags/{tag_id} — aio-update-tag */
+    updateProjectTag(init) {
+      return unwrap('PATCH', client.PATCH('/v2/workspaces/{id}/projects/{project_id}/aio/tags/{tag_id}', init));
+    },
+  };
+}