@zenalexa/unicli 0.219.0 → 0.220.0

package/src/adapters/steam/app.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import {
+  decodeSteamHtml,
+  mapSteamAppRow,
+  requireSteamAppId,
+  requireSteamCountryCode,
+  steamPriceCents,
+} from "./app.js";
+
+describe("steam agent-facing app command", () => {
+  it("validates app ids and country codes", () => {
+    expect(requireSteamAppId(" 620 ")).toBe("620");
+    expect(() => requireSteamAppId("portal")).toThrow("positive integer");
+    expect(requireSteamCountryCode(undefined)).toBe("us");
+    expect(requireSteamCountryCode(" CN ")).toBe("cn");
+    expect(() => requireSteamCountryCode("usa")).toThrow("two-letter");
+  });
+
+  it("decodes Steam text and converts cent prices", () => {
+    expect(decodeSteamHtml("Portal & Co-op's Test")).toBe(
+      "Portal & Co-op's Test",
+    );
+    expect(steamPriceCents(999)).toBe(9.99);
+    expect(steamPriceCents(null)).toBeNull();
+  });
+
+  it("maps Steam appdetails data to stable columns", () => {
+    expect(
+      mapSteamAppRow("620", {
+        steam_appid: 620,
+        name: "Portal 2 & Soundtrack",
+        type: "game",
+        is_free: false,
+        release_date: { date: "Apr 18, 2011" },
+        developers: ["Valve"],
+        publishers: ["Valve"],
+        price_overview: { final: 999, currency: "USD" },
+        metacritic: { score: 95 },
+        recommendations: { total: 450000 },
+        genres: [{ description: "Puzzle" }, { description: "Co-op" }],
+        categories: [{ description: "Single-player" }, { name: "Steam Cloud" }],
+        short_description: "The sequel & test chambers.",
+        website: "https://www.thinkwithportals.com/",
+      }),
+    ).toEqual({
+      id: "620",
+      name: "Portal 2 & Soundtrack",
+      type: "game",
+      isFree: false,
+      releaseDate: "Apr 18, 2011",
+      developers: "Valve",
+      publishers: "Valve",
+      price: 9.99,
+      currency: "USD",
+      metacritic: 95,
+      recommendations: 450000,
+      genres: "Puzzle, Co-op",
+      categories: "Single-player, Steam Cloud",
+      shortDescription: "The sequel & test chambers.",
+      website: "https://www.thinkwithportals.com/",
+      url: "https://store.steampowered.com/app/620/",
+    });
+  });
+
+  it("returns zero price for free apps", () => {
+    expect(mapSteamAppRow("10", { is_free: true }).price).toBe(0);
+  });
+});

package/src/adapters/steam/app.ts

@@ -0,0 +1,218 @@
+/**
+ * @owner   src/adapters/steam/app.ts
+ * @does    Register agent-facing Steam app storefront detail command.
+ * @needs   Steam appdetails API, strict app ids, storefront country code validation.
+ * @feeds   surface coverage ledger, Steam app detail workflows, storefront metadata readers.
+ * @breaks  Steam appdetails envelope drift or regional availability changes can hide app metadata.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const STEAM_STORE = "https://store.steampowered.com";
+
+interface SteamNamedEntry {
+  description?: unknown;
+  name?: unknown;
+}
+
+interface SteamAppData {
+  steam_appid?: unknown;
+  name?: unknown;
+  type?: unknown;
+  is_free?: unknown;
+  release_date?: { date?: unknown };
+  developers?: unknown;
+  publishers?: unknown;
+  price_overview?: {
+    final?: unknown;
+    currency?: unknown;
+  };
+  metacritic?: { score?: unknown };
+  recommendations?: { total?: unknown };
+  genres?: unknown;
+  categories?: unknown;
+  short_description?: unknown;
+  website?: unknown;
+}
+
+interface SteamAppWrapper {
+  success?: unknown;
+  data?: SteamAppData;
+}
+
+type SteamAppEnvelope = Record<string, SteamAppWrapper | undefined>;
+
+const HTML_ENTITIES: Record<string, string> = {
+  "&amp;": "&",
+  "&lt;": "<",
+  "&gt;": ">",
+  "&quot;": '"',
+  "&apos;": "'",
+  "&#39;": "'",
+  "&nbsp;": " ",
+};
+
+function stringField(value: unknown): string {
+  return value === undefined || value === null ? "" : String(value);
+}
+
+function numberOrNull(value: unknown): number | null {
+  if (value === undefined || value === null || value === "") return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+export function decodeSteamHtml(value: unknown): string {
+  return String(value ?? "")
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, hex: string) => {
+      const code = Number.parseInt(hex, 16);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : "";
+    })
+    .replace(/&#(\d+);/g, (_, dec: string) => {
+      const code = Number.parseInt(dec, 10);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : "";
+    })
+    .replace(/&(amp|lt|gt|quot|apos|#39|nbsp);/g, (match) => {
+      return HTML_ENTITIES[match] ?? match;
+    });
+}
+
+export function requireSteamAppId(value: unknown): string {
+  const id = String(value ?? "").trim();
+  if (!/^\d+$/.test(id)) {
+    throw new Error("steam app id must be a positive integer.");
+  }
+  return id;
+}
+
+export function requireSteamCountryCode(
+  value: unknown,
+  fallback = "us",
+): string {
+  const raw =
+    value === undefined || value === null || value === "" ? fallback : value;
+  const code = String(raw).trim().toLowerCase();
+  if (!/^[a-z]{2}$/.test(code)) {
+    throw new Error(
+      "steam currency must be a two-letter storefront country code.",
+    );
+  }
+  return code;
+}
+
+export function steamPriceCents(value: unknown): number | null {
+  const cents = numberOrNull(value);
+  return cents === null ? null : Number((cents / 100).toFixed(2));
+}
+
+function joinSteamNames(value: unknown): string {
+  if (!Array.isArray(value)) return "";
+  return value
+    .map((entry: SteamNamedEntry | string) => {
+      if (typeof entry === "string") return entry;
+      return stringField(entry.description || entry.name);
+    })
+    .filter(Boolean)
+    .join(", ");
+}
+
+export function mapSteamAppRow(
+  appId: string,
+  data: SteamAppData,
+): Record<string, unknown> {
+  const id = stringField(data.steam_appid || appId);
+  const isFree = data.is_free === true;
+  return {
+    id,
+    name: decodeSteamHtml(data.name),
+    type: stringField(data.type),
+    isFree,
+    releaseDate: stringField(data.release_date?.date),
+    developers: Array.isArray(data.developers)
+      ? data.developers.join(", ")
+      : "",
+    publishers: Array.isArray(data.publishers)
+      ? data.publishers.join(", ")
+      : "",
+    price: isFree ? 0 : steamPriceCents(data.price_overview?.final),
+    currency: stringField(data.price_overview?.currency).toUpperCase(),
+    metacritic: numberOrNull(data.metacritic?.score),
+    recommendations: numberOrNull(data.recommendations?.total),
+    genres: joinSteamNames(data.genres),
+    categories: joinSteamNames(data.categories),
+    shortDescription: decodeSteamHtml(data.short_description),
+    website: stringField(data.website),
+    url: `${STEAM_STORE}/app/${id}/`,
+  };
+}
+
+async function fetchSteamApp(
+  appId: string,
+  countryCode: string,
+): Promise<SteamAppData> {
+  const url = new URL(`${STEAM_STORE}/api/appdetails`);
+  url.searchParams.set("appids", appId);
+  url.searchParams.set("l", "en");
+  url.searchParams.set("cc", countryCode);
+  const response = await fetch(url, {
+    headers: {
+      Accept: "application/json",
+      "User-Agent": "unicli-steam/1.0 (https://github.com/olo-dot-io/Uni-CLI)",
+    },
+  });
+  if (!response.ok)
+    throw new Error(`Steam app returned HTTP ${response.status}.`);
+  const envelope = (await response.json()) as SteamAppEnvelope;
+  const wrapper = envelope[appId];
+  if (!wrapper || wrapper.success !== true || !wrapper.data) {
+    throw new Error(`Steam app id ${appId} returned no data.`);
+  }
+  return wrapper.data;
+}
+
+cli({
+  site: "steam",
+  name: "app",
+  description: "Steam storefront detail for a single app id",
+  domain: "store.steampowered.com",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    {
+      name: "id",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Numeric Steam app id",
+    },
+    {
+      name: "currency",
+      type: "str",
+      default: "us",
+      description: "Storefront country code",
+    },
+  ],
+  columns: [
+    "id",
+    "name",
+    "type",
+    "isFree",
+    "releaseDate",
+    "developers",
+    "publishers",
+    "price",
+    "currency",
+    "metacritic",
+    "recommendations",
+    "genres",
+    "categories",
+    "shortDescription",
+    "website",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const id = requireSteamAppId(kwargs.id);
+    const countryCode = requireSteamCountryCode(kwargs.currency);
+    return [mapSteamAppRow(id, await fetchSteamApp(id, countryCode))];
+  },
+});

package/src/adapters/tiktok/creator-videos.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it, vi } from "vitest";
+import { resolveCommand } from "../../registry.js";
+import {
+  buildTikTokItemListRequest,
+  extractTikTokUsername,
+  normalizeTikTokCreatorVideoRow,
+  requireTikTokCursor,
+  requireTikTokPositiveInt,
+} from "./creator-videos.js";
+
+function pageMock(evaluateResults: unknown[]) {
+  const evaluate = vi.fn();
+  for (const result of evaluateResults) evaluate.mockResolvedValueOnce(result);
+  evaluate.mockResolvedValue({
+    ok: true,
+    data: { item_list: [], has_more: false },
+  });
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    wait: vi.fn().mockResolvedValue(undefined),
+    evaluate,
+  };
+}
+
+const apiItem = {
+  item_id: "7350000000000000000",
+  desc: "hello\nworld",
+  create_time: 1710000000,
+  play_count: "123",
+  like_count: "12",
+  comment_count: "3",
+  favorite_count: "4",
+  share_count: "5",
+  author: { uniqueId: "creator" },
+};
+
+describe("tiktok creator-videos agent-facing command", () => {
+  it("validates limits, cursors, and request bodies", () => {
+    expect(requireTikTokPositiveInt(undefined, "limit", 20, 250)).toBe(20);
+    expect(requireTikTokPositiveInt("2", "limit", 20, 250)).toBe(2);
+    expect(() => requireTikTokPositiveInt(0, "limit", 20, 250)).toThrow(
+      "positive integer",
+    );
+    expect(() => requireTikTokPositiveInt(251, "limit", 20, 250)).toThrow(
+      "<= 250",
+    );
+    expect(requireTikTokCursor(undefined)).toBe(0);
+    expect(requireTikTokCursor("42")).toBe(42);
+    expect(() => requireTikTokCursor("abc")).toThrow("cursor");
+    expect(buildTikTokItemListRequest(4, 10)).toMatchObject({
+      cursor: 4,
+      size: 10,
+      query: { sort_orders: [{ field_name: "create_time", order: 2 }] },
+    });
+  });
+
+  it("normalizes TikTok Studio API rows", () => {
+    expect(normalizeTikTokCreatorVideoRow(apiItem)).toMatchObject({
+      video_id: "7350000000000000000",
+      title: "hello world",
+      views: 123,
+      likes: 12,
+      comments: 3,
+      saves: 4,
+      shares: 5,
+      url: "https://www.tiktok.com/@creator/video/7350000000000000000",
+    });
+    expect(normalizeTikTokCreatorVideoRow({ desc: "missing id" })).toBeNull();
+    expect(
+      extractTikTokUsername({
+        play_addr: ["https://example.invalid/video?user_text=test_user&x=1"],
+      }),
+    ).toBe("test_user");
+  });
+
+  it("fetches creator videos from TikTok Studio", async () => {
+    const command = resolveCommand("tiktok", "creator-videos")?.command;
+    const page = pageMock([
+      {
+        ok: true,
+        data: {
+          status_code: 0,
+          status_msg: "success",
+          item_list: [apiItem],
+          has_more: false,
+        },
+      },
+    ]);
+    await expect(command!.func!(page, { limit: 1 })).resolves.toEqual([
+      expect.objectContaining({
+        video_id: "7350000000000000000",
+        title: "hello world",
+        views: 123,
+        likes: 12,
+        url: "https://www.tiktok.com/@creator/video/7350000000000000000",
+      }),
+    ]);
+    expect(page.goto).toHaveBeenCalledWith(
+      "https://www.tiktok.com/tiktokstudio/content",
+      { waitUntil: "load", settleMs: 6000 },
+    );
+  });
+
+  it("fails before navigation on invalid args", async () => {
+    const command = resolveCommand("tiktok", "creator-videos")?.command;
+    const page = pageMock([]);
+    await expect(command!.func!(page, { limit: 0 })).rejects.toThrow(
+      "positive integer",
+    );
+    await expect(command!.func!(page, { cursor: "abc" })).rejects.toThrow(
+      "cursor",
+    );
+    expect(page.goto).not.toHaveBeenCalled();
+  });
+
+  it("classifies auth, API, empty, and missing-id states", async () => {
+    const command = resolveCommand("tiktok", "creator-videos")?.command;
+    await expect(
+      command!.func!(pageMock([{ ok: false, status: 403 }]), { limit: 1 }),
+    ).rejects.toThrow("requires login");
+    await expect(
+      command!.func!(
+        pageMock([
+          {
+            ok: true,
+            data: {
+              status_code: 1001,
+              status_msg: "creator permission denied",
+            },
+          },
+        ]),
+        { limit: 1 },
+      ),
+    ).rejects.toThrow("requires login");
+    await expect(
+      command!.func!(
+        pageMock([
+          { ok: true, data: { status_code: 500, status_msg: "fail" } },
+        ]),
+        { limit: 1 },
+      ),
+    ).rejects.toThrow("item_list failed");
+    await expect(
+      command!.func!(
+        pageMock([{ ok: true, data: { item_list: [], has_more: false } }]),
+        {
+          limit: 1,
+        },
+      ),
+    ).rejects.toThrow("No TikTok Studio creator videos");
+    await expect(
+      command!.func!(
+        pageMock([{ ok: true, data: { item_list: [{ desc: "missing" }] } }]),
+        { limit: 1 },
+      ),
+    ).rejects.toThrow("stable video_id");
+  });
+});