@witchpot/gmc 0.5.0 → 0.8.0

package/src/workflows.js

@@ -11,6 +11,7 @@ import {
   composeResolvePayload,
   composeReviewPatternsPayload,
   composeShowcaseFitPayload,
+  composeShowcaseHistoryPayload,
   getPreferredShowcaseTags,
   mergeSearchPages
 } from "@witchpot/gmc-core";
@@ -22,7 +23,8 @@ export {
   composeComparePayload,
   composeResolvePayload,
   composeReviewPatternsPayload,
-  composeShowcaseFitPayload
+  composeShowcaseFitPayload,
+  composeShowcaseHistoryPayload
 };
 
 export async function executeRequestPlan(baseUrl, request, { apiKey }) {
@@ -47,6 +49,9 @@ export async function executeRequestPlan(baseUrl, request, { apiKey }) {
   if (request.kind === "showcaseFit") {
     return executeShowcaseFitRequest(baseUrl, request, { apiKey });
   }
+  if (request.kind === "showcaseHistory") {
+    return executeShowcaseHistoryRequest(baseUrl, request, { apiKey });
+  }
 
   const response = await fetchJson(createRequestUrl(baseUrl, request), {
     apiKey,
@@ -240,6 +245,15 @@ async function executeShowcaseFitRequest(baseUrl, request, { apiKey }) {
   });
 }
 
+async function executeShowcaseHistoryRequest(baseUrl, request, { apiKey }) {
+  const detailRequest = {
+    path: `/api/v1/steam/games/${encodeURIComponent(request.externalId)}/analysis`,
+    query: request.detailQuery
+  };
+  const detail = await fetchJson(createRequestUrl(baseUrl, detailRequest), { apiKey });
+  return composeShowcaseHistoryPayload(request, { detail });
+}
+
 async function executeSearchPages(baseUrl, searchRequest, sampling, { apiKey }) {
   if (!sampling) {
     return {

package/src/workflows.test.js

@@ -152,6 +152,162 @@ test("executeRequestPlan normalizes list game resolution for cohort workflows",
   }
 });
 
+test("games language-topics passes the insufficient-evidence envelope through untouched", async () => {
+  // NAK-455: the CLI is a transport for this endpoint. Evidence state,
+  // coverage, denominators, and the raw/weighted split must arrive exactly as
+  // the API produced them — an insufficient_evidence answer must never be
+  // flattened into empty rows or a zero.
+  const envelope = {
+    data: {
+      appid: 730,
+      evidenceState: "insufficient_evidence",
+      snapshot: {
+        periodStart: "2026-02-06",
+        periodEnd: "2026-08-06",
+        analysisVersion: "v1",
+        generatedAt: "2026-08-06T04:00:00.000Z"
+      },
+      estimateCaveat: "Weighted values are estimates.",
+      coverage: {
+        totalRows: 226,
+        rowsAtThreshold: 0,
+        languagesAtThreshold: 0,
+        topicsAtThreshold: 0,
+        appliedMinReviews: 30,
+        insufficientRowsReturned: 1,
+        insufficientRowsTruncated: false
+      },
+      rows: [
+        {
+          appid: 730,
+          clusterId: 11,
+          topic: "performance",
+          language: "german",
+          counts: {
+            sourceReviews: 400,
+            sampledReviews: 90,
+            analyzedReviews: 21,
+            distinctReviews: 12
+          },
+          estimates: { samplingWeightMethod: "source_over_analyzed_by_language_voted_up_v1" },
+          evidence: { minimumN: 30, status: "insufficient_evidence", meetsRequestedThreshold: false }
+        }
+      ]
+    },
+    meta: { requestId: "req_test" },
+    warnings: []
+  };
+
+  const originalFetch = globalThis.fetch;
+  const seenUrls = [];
+  globalThis.fetch = async (url) => {
+    seenUrls.push(String(url));
+    return jsonResponse(envelope);
+  };
+
+  try {
+    const payload = await executeRequestPlan("https://gamemarketcopilot.com", {
+      path: "/api/v1/steam/games/730/review-topics/languages",
+      query: { include_insufficient: "true" }
+    }, { apiKey: "gmck_test" });
+
+    assert.deepEqual(payload, envelope);
+    assert.equal(payload.data.evidenceState, "insufficient_evidence");
+    assert.equal(payload.data.coverage.totalRows, 226);
+    assert.equal(payload.data.rows[0].counts.distinctReviews, 12);
+    assert.deepEqual(seenUrls, [
+      "https://gamemarketcopilot.com/api/v1/steam/games/730/review-topics/languages?include_insufficient=true"
+    ]);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("games review-history passes the three arrays through untouched", async () => {
+  // NAK-428: the CLI is a transport for this endpoint. An empty events or
+  // discountWindows array is a COLLECTION state the agent has to see as-is —
+  // the CLI must never drop, merge, or window the arrays, and must never turn
+  // an unmatched (open) discount window into a closed one.
+  const envelope = {
+    data: {
+      series: [
+        { date: "2026-08-01", totalReviews: 1000 },
+        { date: "2026-08-03", totalReviews: 1040 }
+      ],
+      events: [
+        { type: "release", date: "2026-07-01" },
+        {
+          type: "announcement",
+          date: "2026-08-02",
+          count: 3,
+          label: "Patch 1.2 is live",
+          url: "https://store.steampowered.com/news/app/730/view/1"
+        }
+      ],
+      discountWindows: [
+        { startDate: "2026-08-01", endDate: "2026-08-05", discountPercent: 33 },
+        { startDate: "2026-08-20", endDate: null, discountPercent: null }
+      ]
+    },
+    meta: { requestId: "req_test" },
+    warnings: []
+  };
+
+  const originalFetch = globalThis.fetch;
+  const seenUrls = [];
+  globalThis.fetch = async (url) => {
+    seenUrls.push(String(url));
+    return jsonResponse(envelope);
+  };
+
+  try {
+    const payload = await executeRequestPlan("https://gamemarketcopilot.com", {
+      path: "/api/v1/steam/games/730/review-history",
+      query: {}
+    }, { apiKey: "gmck_test" });
+
+    assert.deepEqual(payload, envelope);
+    // The gap between 08-01 and 08-03 survives: collection gaps are real and
+    // consumers must scale by date, not by array index.
+    assert.deepEqual(payload.data.series.map((point) => point.date), ["2026-08-01", "2026-08-03"]);
+    assert.equal(payload.data.discountWindows[1].endDate, null);
+    // No query string appended for an endpoint that takes no parameters.
+    assert.deepEqual(seenUrls, [
+      "https://gamemarketcopilot.com/api/v1/steam/games/730/review-history"
+    ]);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("games review-history passes an all-empty payload through as-is", async () => {
+  // Empty arrays mean "nothing collected", never "nothing happened". The CLI
+  // must hand the agent the same empty arrays the API produced rather than
+  // omitting the keys, which would read as absent fields.
+  const envelope = {
+    data: { series: [], events: [], discountWindows: [] },
+    meta: { requestId: "req_test" },
+    warnings: ["static_fixture_data"]
+  };
+
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async () => jsonResponse(envelope);
+
+  try {
+    const payload = await executeRequestPlan("https://gamemarketcopilot.com", {
+      path: "/api/v1/steam/games/730/review-history",
+      query: {}
+    }, { apiKey: "gmck_test" });
+
+    assert.deepEqual(payload, envelope);
+    assert.deepEqual(payload.data.events, []);
+    assert.deepEqual(payload.data.discountWindows, []);
+    assert.deepEqual(payload.warnings, ["static_fixture_data"]);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
 function jsonResponse(payload, status = 200) {
   return {
     ok: status >= 200 && status < 300,