@witchpot/gmc 0.1.0

package/src/requests.js

@@ -0,0 +1,600 @@
+import {
+  COMPARE_FOCUSES,
+  DEFAULT_BENCHMARK_LIMIT,
+  DEFAULT_CAMPAIGN_SIGNALS_LIMIT,
+  DEFAULT_COHORT_WORKFLOW_LIMIT,
+  DEFAULT_RESOLVE_LIMIT,
+  DEFAULT_REVIEW_PATTERNS_LIMIT,
+  DEFAULT_REVIEW_PATTERNS_MAX_TOPICS_PER_GAME,
+  DEFAULT_REVIEW_PATTERNS_MIN_GAMES,
+  DEFAULT_SHOWCASE_FIT_LIMIT,
+  EXIT_USAGE,
+  MAX_SAMPLE_PAGES,
+  MAX_SAMPLE_SIZE
+} from "./constants.js";
+import { matches } from "./args.js";
+import { writeJsonError } from "./output.js";
+
+export function buildRequest(command, options, positional) {
+  if (matches(command, ["status"])) {
+    return {
+      path: "/api/v1/status",
+      query: {}
+    };
+  }
+
+  if (matches(command, ["auth", "status"])) {
+    return {
+      path: "/api/v1/status",
+      query: {}
+    };
+  }
+
+  if (matches(command, ["schema"])) {
+    return {
+      path: "/api/v1/schema",
+      query: {}
+    };
+  }
+
+  if (matches(command, ["games", "search"])) {
+    assertSource(options.source);
+    return {
+      path: "/api/v1/steam/games",
+      query: buildGameSearchQuery(options)
+    };
+  }
+
+  if (matches(command, ["games", "resolve"])) {
+    assertSource(options.source);
+    const query = options.query ?? options.q ?? positional.join(" ");
+    assertResolveQuery(query);
+    return {
+      kind: "resolve",
+      source: "steam",
+      query: String(query),
+      searchRequest: {
+        path: "/api/v1/steam/games",
+        query: {
+          limit: DEFAULT_RESOLVE_LIMIT,
+          ...buildGameSearchQuery({
+            ...options,
+            query
+          })
+        }
+      }
+    };
+  }
+
+  if (matches(command, ["games", "benchmark"])) {
+    assertSource(options.source);
+    const sampling = buildSamplingOptions(options, DEFAULT_BENCHMARK_LIMIT);
+    const query = {
+      sort: "reviews_desc",
+      limit: sampling?.pageLimit ?? DEFAULT_BENCHMARK_LIMIT,
+      ...buildGameSearchQuery(options)
+    };
+    if (sampling && options.limit == null) query.limit = sampling.pageLimit;
+    return {
+      kind: "benchmark",
+      source: "steam",
+      query,
+      sampling,
+      searchRequest: {
+        path: "/api/v1/steam/games",
+        query
+      }
+    };
+  }
+
+  if (matches(command, ["games", "detail"])) {
+    assertSource(options.source);
+    const externalId = positional[0];
+    assertExternalId(externalId, "gmc games detail --source steam <externalId> --json");
+    return {
+      path: `/api/v1/steam/games/${encodeURIComponent(externalId)}`,
+      query: pickQuery(options, {
+        locale: "locale",
+        detail: "detail"
+      })
+    };
+  }
+
+  if (matches(command, ["games", "analysis"])) {
+    assertSource(options.source);
+    const externalId = positional[0];
+    assertExternalId(externalId, "gmc games analysis --source steam <externalId> --sections reviews,marketing --json");
+    return {
+      path: `/api/v1/steam/games/${encodeURIComponent(externalId)}/analysis`,
+      query: pickQuery(options, {
+        sections: "sections",
+        locale: "locale"
+      })
+    };
+  }
+
+  if (matches(command, ["campaigns", "signals"])) {
+    assertSource(options.source);
+    const externalId = positional[0];
+    assertExternalId(externalId, "gmc campaigns signals --source steam <externalId> --json");
+    const limit = assertPositiveIntegerOption(options.limit ?? DEFAULT_CAMPAIGN_SIGNALS_LIMIT, "--limit");
+    return {
+      kind: "campaignSignals",
+      source: "steam",
+      externalId,
+      limit,
+      detailQuery: pickQuery(options, {
+        locale: "locale"
+      })
+    };
+  }
+
+  if (matches(command, ["games", "compare"])) {
+    assertSource(options.source);
+    assertCompareExternalIds(positional);
+    return {
+      kind: "compare",
+      source: "steam",
+      externalIds: positional,
+      focus: assertCompareFocus(options.focus ?? "market"),
+      query: pickQuery(options, {
+        locale: "locale"
+      })
+    };
+  }
+
+  if (matches(command, ["games", "topics"])) {
+    assertSource(options.source);
+    const externalId = positional[0];
+    assertExternalId(externalId, "gmc games topics --source steam <externalId> --json");
+    return {
+      path: `/api/v1/steam/games/${encodeURIComponent(externalId)}/review-topics`,
+      query: pickQuery(options, {
+        limit: "limit",
+        offset: "offset",
+        locale: "locale"
+      })
+    };
+  }
+
+  if (matches(command, ["reviews", "patterns"])) {
+    assertSource(options.source);
+    const isCompare = positional[0] === "compare";
+    const minGames = assertPositiveIntegerOption(
+      options["min-games"] ?? DEFAULT_REVIEW_PATTERNS_MIN_GAMES,
+      "--min-games"
+    );
+    const maxTopicsPerGame = assertPositiveIntegerOption(
+      options["max-topics-per-game"] ?? DEFAULT_REVIEW_PATTERNS_MAX_TOPICS_PER_GAME,
+      "--max-topics-per-game"
+    );
+    const sentiment = options.sentiment == null ? undefined : assertReviewPatternSentiment(options.sentiment);
+    const sampling = buildSamplingOptions(options, DEFAULT_REVIEW_PATTERNS_LIMIT);
+    const query = {
+      sort: "reviews_desc",
+      limit: sampling?.pageLimit ?? DEFAULT_REVIEW_PATTERNS_LIMIT,
+      ...buildGameSearchQuery(options)
+    };
+    if (sampling && options.limit == null) query.limit = sampling.pageLimit;
+
+    return {
+      kind: "reviewPatterns",
+      source: "steam",
+      query,
+      sampling,
+      minGames,
+      maxTopicsPerGame,
+      sentiment,
+      topic: options.topic,
+      compareBy: isCompare ? String(options.segment ?? "price") : undefined,
+      searchRequest: {
+        path: "/api/v1/steam/games",
+        query
+      },
+      topicQuery: {
+        ...pickQuery(options, {
+          locale: "locale"
+        }),
+        limit: maxTopicsPerGame
+      }
+    };
+  }
+
+  if (matches(command, ["marketing", "patterns"])) {
+    return buildCohortEvidenceRequest({
+      workflow: "marketingPatterns",
+      evidenceType: "marketing",
+      sections: ["marketing", "media", "creators"],
+      command,
+      options,
+      positional
+    });
+  }
+
+  if (matches(command, ["marketing", "timing"])) {
+    return buildCohortEvidenceRequest({
+      workflow: "marketingTiming",
+      evidenceType: "marketingTiming",
+      sections: ["marketing"],
+      command,
+      options,
+      positional
+    });
+  }
+
+  if (matches(command, ["creators", "patterns"])) {
+    return buildCohortEvidenceRequest({
+      workflow: "creatorPatterns",
+      evidenceType: "creators",
+      sections: ["creators"],
+      command,
+      options,
+      positional
+    });
+  }
+
+  if (matches(command, ["cohort", "trends"])) {
+    return buildCohortEvidenceRequest({
+      workflow: "cohortTrends",
+      evidenceType: "trends",
+      sections: [],
+      command,
+      options,
+      positional
+    });
+  }
+
+  if (matches(command, ["cohort", "pricing"])) {
+    return buildCohortEvidenceRequest({
+      workflow: "cohortPricing",
+      evidenceType: "pricing",
+      sections: [],
+      command,
+      options,
+      positional
+    });
+  }
+
+  if (matches(command, ["cohort", "brief"])) {
+    return buildCohortEvidenceRequest({
+      workflow: "cohortBrief",
+      evidenceType: "brief",
+      sections: ["reviews", "marketing", "creators", "media", "showcases"],
+      command,
+      options,
+      positional
+    });
+  }
+
+  if (matches(command, ["cohort", "compare"])) {
+    return buildCohortEvidenceRequest({
+      workflow: "cohortCompare",
+      evidenceType: "trends",
+      sections: [],
+      command,
+      options,
+      positional
+    });
+  }
+
+  if (matches(command, ["showcases", "search"])) {
+    const deadlineBefore = options["deadline-before"];
+    if (deadlineBefore != null) assertDate(deadlineBefore, "--deadline-before");
+    return {
+      path: "/api/v1/showcases",
+      query: buildShowcaseSearchQuery(options),
+      transform: deadlineBefore
+        ? (payload) => filterShowcasesByDeadline(payload, String(deadlineBefore))
+        : undefined
+    };
+  }
+
+  if (matches(command, ["showcases", "patterns"])) {
+    return buildCohortEvidenceRequest({
+      workflow: "showcasePatterns",
+      evidenceType: "showcases",
+      sections: ["showcases"],
+      command,
+      options,
+      positional
+    });
+  }
+
+  if (matches(command, ["showcases", "fit"])) {
+    assertSource(options.source);
+    const externalId = positional[0];
+    assertExternalId(externalId, "gmc showcases fit --source steam <externalId> --json");
+    const deadlineBefore = options["deadline-before"];
+    if (deadlineBefore != null) assertDate(deadlineBefore, "--deadline-before");
+    return {
+      kind: "showcaseFit",
+      source: "steam",
+      externalId,
+      tagsOverride: options.tags ? parseCsvString(options.tags) : undefined,
+      deadlineBefore: deadlineBefore ? String(deadlineBefore) : undefined,
+      detailQuery: pickQuery(options, {
+        locale: "locale"
+      }),
+      showcaseQuery: {
+        status: "open",
+        sort: "deadline_asc",
+        limit: DEFAULT_SHOWCASE_FIT_LIMIT,
+        ...buildShowcaseSearchQuery(options)
+      }
+    };
+  }
+
+  return null;
+}
+
+function buildCohortEvidenceRequest({ workflow, evidenceType, sections, options }) {
+  assertSource(options.source);
+  const sampling = buildSamplingOptions(options, DEFAULT_COHORT_WORKFLOW_LIMIT);
+  const query = {
+    sort: "reviews_desc",
+    limit: sampling?.pageLimit ?? DEFAULT_COHORT_WORKFLOW_LIMIT,
+    ...buildGameSearchQuery(options)
+  };
+  if (sampling && options.limit == null) query.limit = sampling.pageLimit;
+  return {
+    kind: "cohortEvidence",
+    source: "steam",
+    workflow,
+    evidenceType,
+    sections,
+    query,
+    sampling,
+    searchRequest: {
+      path: "/api/v1/steam/games",
+      query
+    },
+    analysisQuery: sections.length
+      ? {
+          ...pickQuery(options, {
+            locale: "locale"
+          }),
+          sections: sections.join(",")
+        }
+      : undefined
+  };
+}
+
+export function createRequestUrl(baseUrl, request) {
+  const url = new URL(request.path, baseUrl);
+  for (const [key, value] of Object.entries(request.query)) {
+    if (value != null && value !== "") url.searchParams.set(key, String(value));
+  }
+  return url;
+}
+
+export function buildRequestHeaders(apiKey) {
+  return {
+    accept: "application/json",
+    ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {})
+  };
+}
+
+function pickQuery(options, mapping) {
+  const query = {};
+  for (const [optionName, queryName] of Object.entries(mapping)) {
+    if (options[optionName] != null) query[queryName] = options[optionName];
+  }
+  return query;
+}
+
+function buildGameSearchQuery(options) {
+  const query = pickQuery(options, {
+    query: "q",
+    tags: "tags",
+    "tag-mode": "tagMode",
+    "release-from": "releaseFrom",
+    "release-to": "releaseTo",
+    "reviews-min": "reviewsMin",
+    "reviews-max": "reviewsMax",
+    "rating-min": "ratingMin",
+    "price-min": "priceMin",
+    "price-max": "priceMax",
+    sort: "sort",
+    limit: "limit",
+    offset: "offset",
+    locale: "locale"
+  });
+
+  if (query.tags) query.tags = normalizeTagSlugCsv(query.tags);
+  return query;
+}
+
+function buildShowcaseSearchQuery(options) {
+  return pickQuery(options, {
+    query: "q",
+    tags: "tags",
+    "tag-mode": "tagMode",
+    status: "status",
+    format: "format",
+    country: "country",
+    sort: "sort",
+    limit: "limit",
+    offset: "offset",
+    locale: "locale"
+  });
+}
+
+function assertSource(source = "steam") {
+  if (source !== "steam") {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: "Only --source steam is supported by the current API"
+    });
+    process.exit(EXIT_USAGE);
+  }
+}
+
+function assertDate(value, optionName) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(String(value))) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `${optionName} must use YYYY-MM-DD`
+    });
+    process.exit(EXIT_USAGE);
+  }
+}
+
+function assertPositiveIntegerOption(value, optionName) {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 1) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `${optionName} must be a positive integer`
+    });
+    process.exit(EXIT_USAGE);
+  }
+  return number;
+}
+
+function buildSamplingOptions(options, defaultLimit) {
+  const sampleSize = options["sample-size"];
+  const samplePages = options["sample-pages"];
+  if (sampleSize != null && samplePages != null) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: "Use either --sample-size or --sample-pages, not both"
+    });
+    process.exit(EXIT_USAGE);
+  }
+
+  if (sampleSize == null && samplePages == null) return undefined;
+
+  const pageLimit = assertPositiveIntegerOption(
+    options.limit ?? (sampleSize == null ? defaultLimit : Math.min(Number(sampleSize), 100)),
+    "--limit"
+  );
+  if (pageLimit > 100) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: "--limit must be 100 or less for sampled workflows"
+    });
+    process.exit(EXIT_USAGE);
+  }
+
+  if (sampleSize != null) {
+    const requestedSize = assertBoundedPositiveIntegerOption(sampleSize, "--sample-size", MAX_SAMPLE_SIZE);
+    return {
+      mode: "sample-size",
+      requestedSize,
+      pageLimit
+    };
+  }
+
+  const requestedPages = assertBoundedPositiveIntegerOption(samplePages, "--sample-pages", MAX_SAMPLE_PAGES);
+  return {
+    mode: "sample-pages",
+    requestedPages,
+    pageLimit
+  };
+}
+
+function assertBoundedPositiveIntegerOption(value, optionName, maxValue) {
+  const number = assertPositiveIntegerOption(value, optionName);
+  if (number > maxValue) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `${optionName} must be ${maxValue} or less`
+    });
+    process.exit(EXIT_USAGE);
+  }
+  return number;
+}
+
+function assertReviewPatternSentiment(value) {
+  const sentiment = String(value);
+  if (!["positive", "negative", "mixed"].includes(sentiment)) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: "--sentiment must be one of: positive, negative, mixed"
+    });
+    process.exit(EXIT_USAGE);
+  }
+  return sentiment;
+}
+
+function assertExternalId(value, usage) {
+  if (!value) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `Missing externalId. Usage: ${usage}`
+    });
+    process.exit(EXIT_USAGE);
+  }
+}
+
+function assertResolveQuery(value) {
+  if (value == null || String(value).trim() === "") {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: "Missing query. Usage: gmc games resolve --source steam --query <title> --json"
+    });
+    process.exit(EXIT_USAGE);
+  }
+}
+
+function assertCompareExternalIds(values) {
+  if (values.length < 2) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: "Missing comparison targets. Usage: gmc games compare --source steam <externalId> <externalId...> --json"
+    });
+    process.exit(EXIT_USAGE);
+  }
+  if (values.length > 5) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: "gmc games compare accepts at most 5 external IDs"
+    });
+    process.exit(EXIT_USAGE);
+  }
+}
+
+function assertCompareFocus(value) {
+  if (!COMPARE_FOCUSES.includes(value)) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `--focus must be one of: ${COMPARE_FOCUSES.join(", ")}`
+    });
+    process.exit(EXIT_USAGE);
+  }
+  return value;
+}
+
+function parseCsvString(value) {
+  return String(value)
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+function normalizeTagSlugCsv(value) {
+  return parseCsvString(value)
+    .map((tag) => tag
+      .toLowerCase()
+      .replace(/['’]/g, "")
+      .replace(/&/g, " and ")
+      .replace(/[^a-z0-9]+/g, "_")
+      .replace(/^_+|_+$/g, ""))
+    .filter(Boolean)
+    .join(",");
+}
+
+export function filterShowcasesByDeadline(payload, deadlineBefore) {
+  if (!payload || !Array.isArray(payload.data)) return payload;
+  return {
+    ...payload,
+    data: payload.data.filter((showcase) => {
+      if (!showcase || typeof showcase !== "object" || !showcase.deadline) return false;
+      return String(showcase.deadline) <= deadlineBefore;
+    }),
+    warnings: [
+      ...(payload.warnings ?? []),
+      "deadline-before was applied client-side by the gmc CLI"
+    ]
+  };
+}