@witchpot/gmc 0.1.7 → 0.1.9

package/src/workflows.js

@@ -30,7 +30,10 @@ export async function executeRequestPlan(baseUrl, request, { apiKey }) {
 }
 
 async function executeCohortEvidenceRequest(baseUrl, request, { apiKey }) {
-  const sampled = await executeSearchPages(baseUrl, request.searchRequest, request.sampling, { apiKey });
+  const [sampled, count] = await Promise.all([
+    executeSearchPages(baseUrl, request.searchRequest, request.sampling, { apiKey }),
+    fetchOptionalCount(baseUrl, request.countRequest, { apiKey })
+  ]);
   const search = mergeSearchPages(sampled.searches, request.sampling);
   const games = Array.isArray(search?.data) ? search.data : [];
   const analysisResults = request.analysisQuery
@@ -69,6 +72,7 @@ async function executeCohortEvidenceRequest(baseUrl, request, { apiKey }) {
 
   return composeCohortEvidencePayload(request, {
     search,
+    count,
     searches: sampled.searches,
     searchPageErrors: sampled.pageErrors,
     analysisResults
@@ -81,8 +85,11 @@ async function executeResolveRequest(baseUrl, request, { apiKey }) {
 }
 
 async function executeBenchmarkRequest(baseUrl, request, { apiKey }) {
-  const sampled = await executeSearchPages(baseUrl, request.searchRequest, request.sampling, { apiKey });
-  return composeBenchmarkPayload(request, sampled);
+  const [sampled, count] = await Promise.all([
+    executeSearchPages(baseUrl, request.searchRequest, request.sampling, { apiKey }),
+    fetchOptionalCount(baseUrl, request.countRequest, { apiKey })
+  ]);
+  return composeBenchmarkPayload(request, { ...sampled, count });
 }
 
 async function executeCompareRequest(baseUrl, request, { apiKey }) {
@@ -116,7 +123,10 @@ async function executeCompareRequest(baseUrl, request, { apiKey }) {
 }
 
 async function executeReviewPatternsRequest(baseUrl, request, { apiKey }) {
-  const sampled = await executeSearchPages(baseUrl, request.searchRequest, request.sampling, { apiKey });
+  const [sampled, count] = await Promise.all([
+    executeSearchPages(baseUrl, request.searchRequest, request.sampling, { apiKey }),
+    fetchOptionalCount(baseUrl, request.countRequest, { apiKey })
+  ]);
   const search = mergeSearchPages(sampled.searches, request.sampling);
   const games = Array.isArray(search?.data) ? search.data : [];
   const topicResults = await Promise.all(
@@ -153,6 +163,7 @@ async function executeReviewPatternsRequest(baseUrl, request, { apiKey }) {
 
   return composeReviewPatternsPayload(request, {
     search,
+    count,
     searches: sampled.searches,
     searchPageErrors: sampled.pageErrors,
     topicResults
@@ -243,6 +254,11 @@ async function executeSearchPages(baseUrl, searchRequest, sampling, { apiKey })
   };
 }
 
+async function fetchOptionalCount(baseUrl, countRequest, { apiKey }) {
+  if (!countRequest) return undefined;
+  return fetchJson(createRequestUrl(baseUrl, countRequest), { apiKey });
+}
+
 function shouldFetchNextSamplePage(sampling, searches) {
   if (sampling.mode === "sample-pages") return searches.length < sampling.requestedPages;
   const fetchedRows = searches.reduce((sum, search) => sum + asArray(search?.data).length, 0);
@@ -383,6 +399,8 @@ export function composeBenchmarkPayload(request, search, options = {}) {
     : search;
   const games = Array.isArray(mergedSearch?.data) ? mergedSearch.data : [];
   const sample = buildSampleMetadata(request, searches, games, pageErrors);
+  const totalMatches = getTotalMatches(search.count, mergedSearch?.pagination);
+  const pagination = withPaginationTotal(mergedSearch?.pagination, totalMatches);
 
   return {
     data: {
@@ -391,19 +409,19 @@ export function composeBenchmarkPayload(request, search, options = {}) {
       workflow: "gamesBenchmark",
       inputs: {
         filters: request.query,
-        ...(sample ? { sample: buildEvidencePackSample(sample, games.length) } : {
-          sample: buildReturnedPageSample(mergedSearch?.pagination, games.length)
+        ...(sample ? { sample: buildEvidencePackSample(sample, games.length, totalMatches) } : {
+          sample: buildReturnedPageSample(pagination, games.length, totalMatches)
         })
       },
       query: request.query,
       summary: withSummaryBasis(
-        buildBenchmarkSummary(games, mergedSearch?.pagination, request.source, { sampled: Boolean(sample) }),
+        buildBenchmarkSummary(games, pagination, request.source, { sampled: Boolean(sample) }),
         sample ? "bounded_sample" : "returned_page"
       ),
       ...(sample
         ? {
             sampledSummary: withSummaryBasis(
-              buildBenchmarkSummary(games, mergedSearch?.pagination, request.source, { sampled: true }),
+              buildBenchmarkSummary(games, pagination, request.source, { sampled: true }),
               "bounded_sample"
             )
           }
@@ -424,11 +442,15 @@ export function composeBenchmarkPayload(request, search, options = {}) {
       requestId,
       composedBy: "gmc-cli",
       ...(sample ? { sample } : {}),
-      upstreamRequests: buildSearchUpstreamRequests(searches, pageErrors)
+      upstreamRequests: [
+        ...buildSearchUpstreamRequests(searches, pageErrors),
+        ...buildCountUpstreamRequests(search.count)
+      ]
     },
-    ...(mergedSearch?.pagination ? { pagination: mergedSearch.pagination } : {}),
+    ...(pagination ? { pagination } : {}),
     warnings: uniqueStrings([
       ...searches.flatMap((entry) => safeWarnings(entry)),
+      ...safeWarnings(search.count),
       ...pageErrors.map((entry) => `benchmark sample page failed at offset ${entry.offset}: ${entry.error?.code ?? "CLI_API_ERROR"}`),
       sample
         ? "sampledSummary is computed from bounded sampled pages; it is not a full market-size estimate"
@@ -457,6 +479,7 @@ export function composeReviewPatternsPayload(request, result, options = {}) {
   const includedGames = normalizedGames.filter((game) => !game.skippedReason);
   const usableGames = includedGames.filter((game) => game.topics.length > 0);
   const sample = buildSampleMetadata(request, searches, games, searchPageErrors);
+  const totalMatches = getTotalMatches(result.count, result.search?.pagination);
   const skipped = normalizedGames
     .filter((game) => game.skippedReason)
     .map((game) => ({
@@ -469,6 +492,7 @@ export function composeReviewPatternsPayload(request, result, options = {}) {
     }));
   const warnings = uniqueStrings([
     ...safeWarnings(result.search),
+    ...safeWarnings(result.count),
     ...searches.flatMap((entry) => safeWarnings(entry)),
     ...searchPageErrors.map((entry) => `review pattern sample page failed at offset ${entry.offset}: ${entry.error?.code ?? "CLI_API_ERROR"}`),
     ...topicResults.flatMap((entry) => safeWarnings(entry.topics)),
@@ -491,8 +515,8 @@ export function composeReviewPatternsPayload(request, result, options = {}) {
         ...(request.topic ? { topic: request.topic } : {}),
         ...(request.compareBy ? { compareBy: request.compareBy } : {}),
         ...(sample
-          ? { sample: buildEvidencePackSample(sample, usableGames.length) }
-          : { sample: buildReturnedPageSample(result.search?.pagination, usableGames.length) })
+          ? { sample: buildEvidencePackSample(sample, usableGames.length, totalMatches) }
+          : { sample: buildReturnedPageSample(result.search?.pagination, usableGames.length, totalMatches) })
       },
       cohort: {
         query: request.query,
@@ -505,7 +529,7 @@ export function composeReviewPatternsPayload(request, result, options = {}) {
         usableGames: usableGames.length,
         skippedGames: skipped.length,
         skippedReasons: tallySkippedReasons(skipped),
-        totalMatches: result.search?.pagination?.total,
+        ...(typeof totalMatches === "number" ? { totalMatches } : {}),
         included: usableGames.map((game) => ({
           source: request.source,
           externalId: game.externalId,
@@ -521,7 +545,7 @@ export function composeReviewPatternsPayload(request, result, options = {}) {
         skipped
       },
       summary: withSummaryBasis(
-        buildReviewPatternsSummary(request, usableGames, skipped, result.search?.pagination),
+        buildReviewPatternsSummary(request, usableGames, skipped, withPaginationTotal(result.search?.pagination, totalMatches)),
         sample ? "bounded_sample" : "returned_page"
       ),
       patterns: buildReviewPatterns(usableGames),
@@ -547,6 +571,7 @@ export function composeReviewPatternsPayload(request, result, options = {}) {
       ...(sample ? { sample } : {}),
       upstreamRequests: [
         ...buildSearchUpstreamRequests(searches, searchPageErrors),
+        ...buildCountUpstreamRequests(result.count),
         ...topicResults
           .filter((entry) => entry.topics || entry.error)
           .map((entry) => ({
@@ -559,7 +584,7 @@ export function composeReviewPatternsPayload(request, result, options = {}) {
           }))
       ]
     },
-    ...(result.search?.pagination ? { pagination: result.search.pagination } : {}),
+    ...(result.search?.pagination ? { pagination: withPaginationTotal(result.search.pagination, totalMatches) } : {}),
     ...(warnings.length ? { warnings } : {})
   };
 }
@@ -670,8 +695,10 @@ export function composeCohortEvidencePayload(request, result, options = {}) {
       ...(entry.error ? { error: entry.error } : {})
     }));
   const sample = buildSampleMetadata(request, searches, games, searchPageErrors);
+  const totalMatches = getTotalMatches(result.count, result.search?.pagination);
   const warnings = uniqueStrings([
     ...safeWarnings(result.search),
+    ...safeWarnings(result.count),
     ...searches.flatMap((entry) => safeWarnings(entry)),
     ...searchPageErrors.map((entry) => `${request.workflow} sample page failed at offset ${entry.offset}: ${entry.error?.code ?? "CLI_API_ERROR"}`),
     ...analysisResults.flatMap((entry) => safeWarnings(entry.analysis)),
@@ -688,8 +715,8 @@ export function composeCohortEvidencePayload(request, result, options = {}) {
       inputs: {
         filters: request.query,
         sections: request.sections,
-        ...(sample ? { sample: buildEvidencePackSample(sample, included.length) } : {
-          sample: buildReturnedPageSample(result.search?.pagination, included.length)
+        ...(sample ? { sample: buildEvidencePackSample(sample, included.length, totalMatches) } : {
+          sample: buildReturnedPageSample(result.search?.pagination, included.length, totalMatches)
         })
       },
       cohort: {
@@ -698,7 +725,7 @@ export function composeCohortEvidencePayload(request, result, options = {}) {
         usableGames: included.length,
         skippedGames: skipped.length,
         skippedReasons: tallySkippedReasons(skipped),
-        totalMatches: result.search?.pagination?.total,
+        ...(typeof totalMatches === "number" ? { totalMatches } : {}),
         included: included.map((entry) => ({
           source: request.source,
           externalId: entry.externalId,
@@ -716,12 +743,12 @@ export function composeCohortEvidencePayload(request, result, options = {}) {
         skipped
       },
       summary: withSummaryBasis(
-        buildCohortEvidenceSummary(request, included, result.search?.pagination),
+        buildCohortEvidenceSummary(request, included, withPaginationTotal(result.search?.pagination, totalMatches)),
         sample ? "bounded_sample" : "returned_page"
       ),
       patterns: buildCohortEvidencePatterns(request, included),
       ...(request.evidenceType === "pricing" ? { segments: buildPricingSegments(included) } : {}),
-      ...(request.evidenceType === "trends" || request.evidenceType === "brief" ? { trends: buildTrendSummary(included, result.search?.pagination, request.source) } : {}),
+      ...(request.evidenceType === "trends" || request.evidenceType === "brief" ? { trends: buildTrendSummary(included, withPaginationTotal(result.search?.pagination, totalMatches), request.source) } : {}),
       games: included.map((entry) => ({
         source: request.source,
         externalId: entry.externalId,
@@ -744,6 +771,7 @@ export function composeCohortEvidencePayload(request, result, options = {}) {
       ...(sample ? { sample } : {}),
       upstreamRequests: [
         ...buildSearchUpstreamRequests(searches, searchPageErrors),
+        ...buildCountUpstreamRequests(result.count),
         ...analysisResults
           .filter((entry) => entry.analysis || entry.error)
           .map((entry) => ({
@@ -756,7 +784,7 @@ export function composeCohortEvidencePayload(request, result, options = {}) {
           }))
       ]
     },
-    ...(result.search?.pagination ? { pagination: result.search.pagination } : {}),
+    ...(result.search?.pagination ? { pagination: withPaginationTotal(result.search.pagination, totalMatches) } : {}),
     ...(warnings.length ? { warnings } : {})
   };
 }
@@ -1021,7 +1049,7 @@ function mergeSearchPages(searches, sampling) {
       ...(first.pagination ?? {}),
       limit: first.pagination?.limit,
       offset: first.pagination?.offset,
-      total: first.pagination?.total,
+      ...(typeof first.pagination?.total === "number" ? { total: first.pagination.total } : {}),
       nextOffset: last.pagination?.nextOffset
     },
     warnings: uniqueStrings(searches.flatMap((search) => safeWarnings(search)))
@@ -1038,12 +1066,12 @@ function buildSampleMetadata(request, searches, games, pageErrors) {
     fetchedPages: searches.length,
     fetchedGames: games.length,
     skippedPages: pageErrors.length,
-    totalMatches: searches[0]?.pagination?.total,
+    ...(typeof searches[0]?.pagination?.total === "number" ? { totalMatches: searches[0].pagination.total } : {}),
     quotaCaveat: "Sampled workflows issue one search request per fetched page, plus downstream per-game requests when the command needs detail evidence."
   };
 }
 
-function buildEvidencePackSample(sample, returnedRows) {
+function buildEvidencePackSample(sample, returnedRows, totalMatches) {
   return {
     mode: normalizeEvidencePackSampleMode(sample.mode),
     requestedRows: sample.requestedSize,
@@ -1051,16 +1079,31 @@ function buildEvidencePackSample(sample, returnedRows) {
     returnedRows,
     fetchedPages: sample.fetchedPages,
     skippedPages: sample.skippedPages,
-    totalMatches: sample.totalMatches
+    totalMatches: typeof totalMatches === "number" ? totalMatches : sample.totalMatches
   };
 }
 
-function buildReturnedPageSample(pagination, returnedRows) {
+function buildReturnedPageSample(pagination, returnedRows, totalMatches) {
   return {
     mode: "returned_page",
     requestedRows: pagination?.limit,
     returnedRows,
-    totalMatches: pagination?.total
+    totalMatches: typeof totalMatches === "number" ? totalMatches : pagination?.total
+  };
+}
+
+function getTotalMatches(count, pagination) {
+  const countValue = numericValue(count?.data?.count);
+  if (Number.isFinite(countValue)) return countValue;
+  const paginationTotal = numericValue(pagination?.total);
+  return Number.isFinite(paginationTotal) ? paginationTotal : undefined;
+}
+
+function withPaginationTotal(pagination, totalMatches) {
+  if (typeof totalMatches !== "number") return pagination;
+  return {
+    ...(pagination ?? {}),
+    total: totalMatches
   };
 }
 
@@ -1096,6 +1139,17 @@ function buildSearchUpstreamRequests(searches, pageErrors = []) {
   ];
 }
 
+function buildCountUpstreamRequests(count) {
+  if (!count) return [];
+  return [{
+    kind: "count",
+    requestId: count?.meta?.requestId,
+    source: count?.meta?.source,
+    entitlements: count?.meta?.entitlements,
+    count: count?.data?.count
+  }];
+}
+
 function buildReviewPatternGame(request, entry) {
   const game = entry.game ?? {};
   const externalId = asString(entry.externalId ?? game?.externalId ?? game?.appid);

package/src/workflows.test.js

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 
-import { composeCohortEvidencePayload } from "./workflows.js";
+import { composeBenchmarkPayload, composeCohortEvidencePayload } from "./workflows.js";
 
 test("cohort evidence summarizes skipped games by reason", () => {
   const request = {
@@ -78,3 +78,30 @@ test("cohort evidence reports an empty reason tally when nothing is skipped", ()
 
   assert.deepEqual(payload.data.cohort.skippedReasons, {});
 });
+
+test("benchmark attaches exact total only when a count response is supplied", () => {
+  const request = {
+    source: "steam",
+    query: { sort: "reviews_desc", limit: 20, includeTotal: false }
+  };
+  const payload = composeBenchmarkPayload(request, {
+    searches: [{
+      data: [{ appid: 1, title: "Usable", reviews: 100 }],
+      pagination: { limit: 20, offset: 0, nextOffset: 20 },
+      meta: { requestId: "search_req", source: "steam-analysis" }
+    }],
+    pageErrors: [],
+    count: {
+      data: { count: 123 },
+      meta: { requestId: "count_req", source: "steam-analysis" }
+    }
+  }, {
+    generatedAt: "2026-06-12T00:00:00.000Z",
+    requestId: "req_test"
+  });
+
+  assert.equal(payload.data.summary.totalMatches, 123);
+  assert.equal(payload.data.inputs.sample.totalMatches, 123);
+  assert.equal(payload.pagination.total, 123);
+  assert.deepEqual(payload.meta.upstreamRequests.map((entry) => entry.kind), ["search", "count"]);
+});