@adobe/spacecat-shared-project-engine-client 1.13.0 → 1.14.0

package/package.json

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

package/src/errors.js

@@ -0,0 +1,48 @@
+/*
+ * 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
+
+/**
+ * The single typed error the transport facade throws from its `unwrap` seam. It carries the
+ * failing HTTP `method`, the response `status` (or `undefined` when there was no HTTP response —
+ * i.e. an exhausted-network / per-attempt-timeout failure), and the normalized parsed error
+ * `body`. On the network/timeout path the original thrown error is preserved as `cause`.
+ *
+ * This class does NOT translate the failure into an HTTP status for the consumer, redact the
+ * body, or map it onto a domain error — those are consumer-owned per ADR-0001. It exists only to
+ * give consumers a single `instanceof`-checkable type with the raw `{ status, method, body }`.
+ */
+export class ProjectEngineApiError extends Error {
+  /**
+   * @param {number | undefined} status the HTTP response status, or `undefined` when there was no
+   *   HTTP response (network / timeout failure)
+   * @param {string} method the HTTP method of the failing request
+   * @param {unknown} body the normalized parsed error body (`null` when empty/absent)
+   * @param {{ cause?: unknown }} [options] optional `{ cause }` forwarded to `super`, so a wrapped
+   *   network/timeout error keeps its original as `.cause`
+   */
+  constructor(status, method, body, options) {
+    const message = status === undefined
+      ? `Project Engine ${method} request failed`
+      : `Project Engine ${method} request failed with status ${status}`;
+    super(message, options);
+    /** @type {string} */
+    this.name = 'ProjectEngineApiError';
+    /** @type {number | undefined} */
+    this.status = status;
+    /** @type {string} */
+    this.method = method;
+    /** @type {unknown} */
+    this.body = body;
+  }
+}

package/src/index.d.ts

@@ -353,5 +353,30 @@ export declare function createSerenityProjectEngineTransport(
   options: SerenityProjectEngineApiClientOptions,
 ): SerenityProjectEngineTransport;
 
+/**
+ * The single typed error the transport facade throws from its `unwrap` seam. It carries the
+ * failing HTTP `method`, the response `status` (or `undefined` when there was no HTTP response —
+ * an exhausted-network / per-attempt-timeout failure), and the normalized parsed error `body`.
+ * On the network/timeout path the original thrown error is preserved as `cause`. No error→HTTP
+ * translation or redaction — consumer-owned per ADR-0001.
+ *
+ * NOTE: the `readonly` modifiers below are a type-system-only guarantee; the runtime class
+ * (`errors.js`) sets these fields with plain assignment in the constructor.
+ */
+export declare class ProjectEngineApiError extends Error {
+  /** The HTTP response status, or `undefined` when there was no HTTP response. */
+  readonly status: number | undefined;
+  /** The HTTP method of the failing request. */
+  readonly method: string;
+  /** The normalized parsed error body (`null` when empty/absent). */
+  readonly body: unknown;
+  constructor(
+    status: number | undefined,
+    method: string,
+    body: unknown,
+    options?: { cause?: unknown },
+  );
+}
+
 // Re-export the generated contract types for consumers that want them directly.
 export type { paths, components };

package/src/index.js

@@ -14,3 +14,4 @@
 
 export { createSerenityProjectEngineApiClient } from './client.js';
 export { createSerenityProjectEngineTransport } from './rest-transport.js';
+export { ProjectEngineApiError } from './errors.js';

package/src/rest-transport.js

@@ -13,6 +13,7 @@
 // @ts-check
 
 import { createSerenityProjectEngineApiClient } from './client.js';
+import { ProjectEngineApiError } from './errors.js';
 
 /**
  * @typedef {import('./client.js').SerenityProjectEngineApiClientOptions}
@@ -40,14 +41,17 @@ export function createSerenityProjectEngineTransport(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).
+   * promise here (so a network/timeout rejection also flows through this one point), and turns
+   * both failure paths into a {@link ProjectEngineApiError}:
    *
-   * `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.
+   * - a non-2xx HTTP response: the typed client never throws on an HTTP error — it resolves to
+   *   `{ data, error, response }` with the parsed error body in `error` — so the non-2xx is turned
+   *   into a throw here carrying `response.status` + the normalized `body`;
+   * - an exhausted-network / per-attempt-timeout failure: `createRetryingFetch` rethrew the last
+   *   raw error after the retry budget, so the awaited promise rejects. There is no HTTP response
+   *   ⇒ `status` is `undefined`; the original error is preserved as `cause`.
+   *
+   * A 2xx returns the parsed body (or null for an empty body).
    *
    * @template T
    * @param {string} method the HTTP method, for the error message
@@ -55,21 +59,26 @@ export function createSerenityProjectEngineTransport(options) {
    *   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)
+   * @throws {import('./errors.js').ProjectEngineApiError} on a non-2xx response or an
+   *   exhausted-network / per-attempt-timeout failure
    */
   async function unwrap(method, resultPromise) {
-    const { data, error, response } = await resultPromise;
+    let result;
+    try {
+      result = await resultPromise;
+    } catch (cause) {
+      // exhausted-network / per-attempt-timeout path: createRetryingFetch rethrew the last raw
+      // error after the retry budget. No HTTP response ⇒ status undefined; preserve the original
+      // as `cause`.
+      throw new ProjectEngineApiError(undefined, method, null, { cause });
+    }
+    const { data, error, response } = result;
     if (!response.ok) {
-      const { status } = response;
-      // openapi-fetch surfaces an empty error body as '' (not undefined); normalise it to null.
+      // openapi-fetch puts the parsed error body in `error`; fall back to `data`, then 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
+      // openapi-fetch surfaces an empty error body as '' (not undefined); normalise it to null.
       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}`);
+      throw new ProjectEngineApiError(response.status, method, body);
     }
     return data ?? null;
   }