@adobe/spacecat-shared-project-engine-client 1.18.1 → 1.19.0

package/README.md

@@ -47,8 +47,9 @@ const { data, error } = await client.GET('/v1/countries');
 
 The spec is a **vendored file** — `spec/projectengine_swagger_public.yaml` — kept under
 version control. Semrush only provides the file (no endpoint access in the near term), and
-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
+it's **Swagger 2.0** (no v3/v3.1 on offer). The vendored file is **never hand-authored** — the only
+thing that ever lands in it is what Semrush ships; 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. A committed checksum lock
 (`spec/projectengine_swagger_public.yaml.sha256`) is verified by `npm run spec:verify` (wired into
@@ -56,6 +57,18 @@ diverges from the live API, a generation-time overlay corrects the converted art
 explicitly regenerated with `npm run spec:lock` and reviewed. A true live-drift contract test
 against Semrush remains blocked on endpoint access.
 
+Semrush sometimes delivers a **delta** instead of a whole document — a short YAML carrying only the
+paths a release added. Splice those paths into the vendored file verbatim, in sorted position and in
+the file's own block style (sequences flush with their key), leaving every other byte untouched, then
+re-lock. Nothing is hand-authored, so the review evidence is a deep-compare of the spliced paths
+against the delivered YAML:
+
+```bash
+node -e "const y=require('js-yaml'),f=require('fs');
+const a=y.load(f.readFileSync('<delivered>.yaml','utf8')),b=y.load(f.readFileSync('spec/projectengine_swagger_public.yaml','utf8'));
+for (const p of Object.keys(a.paths)) console.log(p, JSON.stringify(a.paths[p])===JSON.stringify(b.paths[p]));"
+```
+
 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
@@ -101,13 +114,20 @@ pip install datamodel-code-generator
 
 ## Spec corrections
 
-The vendored swagger diverges from the live API in three places. A small OpenAPI Overlay
+The vendored swagger diverges from the live API in a number of places. A small OpenAPI Overlay
 (`spec/overlays/corrections.yaml`), applied to the converted OAS3 artifact at generation time by
-`scripts/apply-overlay.mjs`, corrects them; the vendored `spec/projectengine_swagger_public.yaml`
-is never touched.
+`scripts/apply-overlay.mjs`, corrects them; no correction is ever written into the vendored
+`spec/projectengine_swagger_public.yaml`.
 
 - **CR1 — missing endpoint.** Adds `GET /v1/ai_models` (the live global model catalog), which is
   absent from the upstream swagger.
+- **CR23 — missing response field.** Adds `is_paused` to `model.ProjectResponse`. The swagger
+  delta that shipped `pause`/`resume` added the two action paths but left the response schema
+  alone, so the generated type had no way to express whether a project is paused. Live returns the
+  key on every project read.
+- **CR24 — missing status.** Declares the `404` that `pause`/`resume` return for an unknown project
+  id. Live pause is idempotent (a second pause is another `202`); only `resume` uses the declared
+  `409`, and it does so with `{"message": "project is not paused"}`.
 - **CR2 — auth.** The spec models a required `Auth-Data-Jwt` header, but the live API authenticates
   on `Authorization: Bearer <IMS>` only — Semrush accepts the IMS bearer directly. The overlay
   removes `Auth-Data-Jwt` from every operation and adds an `imsBearer` security scheme.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-project-engine-client",
-  "version": "1.18.1",
+  "version": "1.19.0",
   "description": "Shared modules of the Spacecat Services - Semrush Project Engine client and generated types",
   "type": "module",
   "main": "src/index.js",
@@ -63,7 +63,7 @@
     "c8": "11.0.0",
     "chai": "6.2.2",
     "counterfact": "2.14.0",
-    "js-yaml": "4.3.0",
+    "js-yaml": "4.3.1",
     "mocha": "11.7.6",
     "mocha-multi-reporters": "1.5.1",
     "openapi-typescript": "7.13.0",

package/src/client.js

@@ -28,7 +28,7 @@ import { createRetryingFetch, toTokenGetter } from './internal.js';
 /**
  * @typedef {object} SerenityProjectEngineApiClientOptions
  * @property {string} baseUrl Base URL of the Project Engine API — the origin of
- *   `SEMRUSH_PROJECTS_BASE_URL` (e.g. `https://adobe-hackathon.semrush.com`), or the Counterfact
+ *   `SEMRUSH_PROJECTS_BASE_URL` (e.g. `https://www.semrush.com`), or the Counterfact
  *   mock's origin for E2E / local dev. Only `protocol//host` is used; any path is dropped and the
  *   client appends the fixed `/enterprise/projects/api` prefix itself, matching the deployed
  *   api-service transport (`rest-transport.js`).

package/src/generated/types.ts

@@ -883,6 +883,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/workspaces/{id}/projects/{project_id}/pause": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * pause a project
+         * @description pause an AIO project: prompt limits are released and data collection stops while configuration and historical data are preserved
+         */
+        post: operations["projects-pause-project"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/workspaces/{id}/projects/{project_id}/publish": {
         parameters: {
             query?: never;
@@ -903,6 +923,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/workspaces/{id}/projects/{project_id}/resume": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * resume a paused project
+         * @description resume a paused AIO project: re-consumes prompt limits (subject to the same quota check as publishing) and data collection continues
+         */
+        post: operations["projects-resume-project"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/workspaces/{id}/projects/{project_id}/segments": {
         parameters: {
             query?: never;
@@ -2385,6 +2425,8 @@ export interface components {
             /** @description enum: aio,mfour,ci */
             type?: string;
             updated_at?: string;
+            /** @description whether the project is paused: prompt limits released and data collection stopped, configuration and historical data preserved */
+            is_paused: boolean;
         };
         "model.ProjectUpdateRequest": {
             brand_name_display?: string;
@@ -5790,6 +5832,74 @@ export interface operations {
             };
         };
     };
+    "projects-pause-project": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description workspace ID */
+                id: string;
+                /** @description project ID */
+                project_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Accepted */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Unauthorized */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["http_server.BasicResponse"];
+                };
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["http_server.BasicResponse"];
+                };
+            };
+            /** @description Not Found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "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: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["http_server.BasicResponse"];
+                };
+            };
+        };
+    };
     "projects-publish-project": {
         parameters: {
             query?: never;
@@ -5840,6 +5950,74 @@ export interface operations {
             };
         };
     };
+    "projects-resume-project": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description workspace ID */
+                id: string;
+                /** @description project ID */
+                project_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Accepted */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Unauthorized */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["http_server.BasicResponse"];
+                };
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["http_server.BasicResponse"];
+                };
+            };
+            /** @description Not Found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "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: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["http_server.BasicResponse"];
+                };
+            };
+        };
+    };
     "project-list-segments": {
         parameters: {
             query?: {

package/src/index.d.ts

@@ -111,7 +111,7 @@ type TransportData<P extends keyof paths, M extends keyof paths[P]> =
   | null;
 
 /**
- * Intent-named facade over {@link SerenityProjectEngineApiClient}. Wraps the 32 in-spec
+ * Intent-named facade over {@link SerenityProjectEngineApiClient}. Wraps the 34 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
@@ -157,6 +157,18 @@ export interface SerenityProjectEngineTransport {
       TransportInit<'/v1/workspaces/{id}/projects/{project_id}/publish', 'post'>
     >
   ): Promise<TransportData<'/v1/workspaces/{id}/projects/{project_id}/publish', 'post'>>;
+  /** POST /v1/workspaces/{id}/projects/{project_id}/pause — projects-pause-project */
+  pauseProject(
+    ...init: TransportInitParam<
+      TransportInit<'/v1/workspaces/{id}/projects/{project_id}/pause', 'post'>
+    >
+  ): Promise<TransportData<'/v1/workspaces/{id}/projects/{project_id}/pause', 'post'>>;
+  /** POST /v1/workspaces/{id}/projects/{project_id}/resume — projects-resume-project */
+  resumeProject(
+    ...init: TransportInitParam<
+      TransportInit<'/v1/workspaces/{id}/projects/{project_id}/resume', 'post'>
+    >
+  ): Promise<TransportData<'/v1/workspaces/{id}/projects/{project_id}/resume', 'post'>>;
 
   /** GET /v1/workspaces/{id}/projects/{project_id}/ai_models — ai-list-models */
   listAiModels(

package/src/rest-transport.js

@@ -22,7 +22,7 @@ import { ProjectEngineApiError } from './errors.js';
 
 /**
  * Intent-named facade over the raw {@link createSerenityProjectEngineApiClient} openapi-fetch
- * client. It wraps ONLY the 32 in-spec Project Engine operations that spacecat-api-service
+ * client. It wraps ONLY the 34 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
@@ -119,6 +119,14 @@ export function createSerenityProjectEngineTransport(options) {
     publishProject(init) {
       return unwrap('POST', client.POST('/v1/workspaces/{id}/projects/{project_id}/publish', init));
     },
+    /** POST /v1/workspaces/{id}/projects/{project_id}/pause — projects-pause-project */
+    pauseProject(init) {
+      return unwrap('POST', client.POST('/v1/workspaces/{id}/projects/{project_id}/pause', init));
+    },
+    /** POST /v1/workspaces/{id}/projects/{project_id}/resume — projects-resume-project */
+    resumeProject(init) {
+      return unwrap('POST', client.POST('/v1/workspaces/{id}/projects/{project_id}/resume', init));
+    },
 
     // ─── /v1 AI models + benchmarks ───────────────────────────────────────────
     /** GET /v1/workspaces/{id}/projects/{project_id}/ai_models — ai-list-models */